Esta API pode ser usada para divulgar seletivamente a sua sessão de partida multijogadora em uma sala de conversa no Steam. Informe ao Steam quantas vagas estão disponíveis na sessão juntamente com uma string descritiva para entrar na partida e uma notificação será exibida na sala, permitindo que a quantidade de usuários informada "siga" a notificação e entre na sessão. Ajuste a quantidade de vagas abertas caso outros jogadores entrem na sessão por outros meios.

Por exemplo, é possível usar a interface ISteamParties em conjunto com uma sala privada. Crie uma sala privada e use a função ISteamParties::CreateBeacon para criar um "convite aberto" para o grupo com a quantidade de jogadores desejada. A string de conexão do jogo deve indicar o ID da sala privada.

O convite aberto será exibido na localização especificada do Steam (como uma sala de conversa) e também pela API ISteamParties no jogo, como descrito mais abaixo. O Steam "reserva" vagas para a quantidade desejada de jogadores. Quando um usuário clica no convite aberto, o Steam reserva uma vaga para ele e inicia o jogo usando a string de conexão informada.

A sessão de partida que criou o convite aberto será notificada da reserva, assim o jogo pode exibir uma notificação do tipo "Usuário <nome do usuário> está entrando no grupo". Quando o usuário entrar no grupo, a sessão de partida deve chamar a função ISteamParties::OnReservationCompleted para avisar ao Steam que o usuário entrou com sucesso (caso contrário, eventualmente a reserva perderá a validade e o Steam reabrirá a vaga).

Quando todas as vagas do convite aberto forem ocupadas — seja por reservas de usuários que ainda estão abrindo o jogo ou por vagas preenchidas por usuários que já estão no grupo —, este será ocultado e desativado pelo Steam.

Para cancelar o convite aberto — por exemplo, quando o grupo estiver lotado e a partida começar — chame a função ISteamParties::DestroyBeacon.

O lado do cliente desta operação — ver e seguir convites abertos — também pode ser tratado pelo jogo. O jogo pode usar as funções ISteamParties::GetNumActiveBeacons e ISteamParties::GetBeaconDetails para obter uma lista de convites abertos de outros usuários ativos em locais relevantes ao usuário atual. Caso o usuário deseje, chame a função ISteamParties::JoinParty para "seguir" um desses convites abertos.

Funções de membro

Funções de membro de ISteamParties são chamadas por meio da função de acesso global ISteamParties(), que é oferecida pelo arquivo de cabeçalho steam/ISteamMatchmaking.h.

GetNumAvailableBeaconLocations

Nome	Tipo	Descrição
puNumLocations	uint32*	O endereço da variável que receberá o número da resposta.

Recupera a quantidade de locais em que você pode publicar um convite aberto de grupo.

Use este valor para definir o tamanho da lista de resultados na chamada à função ISteamParties::GetAvailableBeaconLocations.

Retorna: bool

GetAvailableBeaconLocations

Nome	Tipo	Descrição
pLocationList	SteamPartyBeaconLocation_t*	A lista que receberá os locais disponíveis para publicar um convite aberto.
uMaxNumLocations	uint32	A quantidade máxima de entradas para inserir na lista acima. Deve ser >= ao resultado da função GetNumAvailableBeaconLocations.

Recupera a lista de locais em que você pode publicar um convite aberto de grupo.

Consulte também: ISteamParties::GetNumAvailableBeaconLocations

Retorna: bool

CreateBeacon

Nome	Tipo	Descrição
unOpenSlots	uint32	A quantidade de vagas reservadas para criar para o convite. Normalmente este valor é igual ao tamanho desejado do grupo, menos 1 (o usuário atual).
pBeaconLocation	SteamPartyBeaconLocation_t*	O local do convite aberto. Deve ser igual a um dos locais retornados pela função ISteamParties::GetAvailableBeaconLocations.
pchConnectString	char *	A string de conexão que será passada ao jogo por um usuário que seguir o convite aberto.
pchMetadata	char *	Metadados adicionais do jogo que podem ser definidos no convite aberto. Tais metadados podem ser recuperados por meio da função ISteamParties::GetBeaconDetails.

Cria um convite aberto. Só é possível ter um convite aberto de cada vez. O Steam exibirá o convite aberto no local especificado e permitirá que até unOpenSlots usuários "sigam" o convite aberto para entrar no grupo.

Caso usuários entrem no grupo por outros meios, ajuste a quantidade de vagas abertas por meio da função ISteamParties::ChangeNumOpenSlots.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada CreateBeaconCallback_t.
Retorna k_uAPICallInvalid se o processo já tiver um convite aberto ativo ou se o local informado for inválido.

OnReservationCompleted

Nome	Tipo	Descrição
ulBeacon	PartyBeaconID_t	O ID do convite aberto criado pelo processo.
steamIDUser	CSteamID	O ID Steam do usuário que está entrando no grupo.

Quando um usuário segue o convite aberto, o Steam reservará uma das vagas abertas no grupo para ele e disparará um retorno de chamada ReservationNotificationCallback_t no jogo. Quando o usuário entrar no grupo, chame a função OnReservationCompleted para notificar o Steam de que o usuário entrou no grupo com sucesso.

ChangeNumOpenSlots

Nome	Tipo	Descrição
ulBeacon	PartyBeaconID_t	O ID do convite aberto criado pelo processo.
unOpenSlots	uint32	A nova quantidade de vagas abertas no grupo.

Se um usuário entrar no grupo por outros meios (como por meio de um convite direto de um amigo no Steam ou pelo sistema de criação de partidas do jogo), o jogo precisa reduzir a quantidade de vagas abertas que o Steam está gerenciando pelo convite aberto. Por exemplo, se um convite aberto foi criado com cinco vagas, o Steam disparou dois retornos de chamada ReservationNotificationCallback_t e depois um terceiro usuário entrou diretamente, chame a função ChangeNumOpenSlots passando o valor 2 no parâmetro unOpenSlots. O valor representa a quantidade total de novos usuários que deseja que o Steam mande para o grupo.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada ChangeNumOpenSlotsCallback_t.
Retorna k_uAPICallInvalid se o ID do convite aberto for inválido.

DestroyBeacon

Nome	Tipo	Descrição
ulBeacon	PartyBeaconID_t	O ID do convite aberto a destruir.

Chame esta função para destruir o convite aberto do Steam. Isso fará com que o Steam interrompa imediatamente a exibição do convite aberto no local escolhido. Observe que usuários que já tenham seguido o convite aberto ainda esperarão conseguir entrar no grupo.

O jogo deve chamar esta função quando o grupo estiver lotado e e partida estiver começando, ou quando o usuário decidir abandonar a criação do grupo. O convite aberto será destruído automaticamente quando o jogo for fechado, mas aconselhamos chamar a função DestroyBeacon no momento certo.

Retorna: bool

GetNumActiveBeacons

Esta função não possui parâmetros.

Recupera a quantidade de convites abertos do jogo ativos criados por outros usuários e que estejam visíveis pelo usuário atual.

Retorna: uint32

GetBeaconByIndex

Nome	Tipo	Descrição
unIndex	uint32	O índice do convite aberto.

Use em conjunto com a função ISteamParties::GetNumActiveBeacons para iterar pelos convites abertos ativos e visíveis ao usuário atual. unIndex é um índice que começa em zero, então itere sobre o intervalo [0, GetNumActiveBeacons() - 1]. O valor de retorno é do tipo PartyBeaconID_t, que pode ser usado com a função ISteamParties::GetBeaconDetails para recuperar dados sobre os convites abertos para posterior exibição ao usuário.

Retorna: PartyBeaconID_t

GetBeaconDetails

Nome	Tipo	Descrição
ulBeaconID	PartyBeaconID_t	O ID do convite aberto a consultar.
pSteamIDBeaconOwner	CSteamID*	O criador do convite aberto.
pLocation	SteamPartyBeaconLocation_t*	O local em que o convite aberto foi publicado.
pchMetadata	char*	Buffer que receberá os metadados adicionais definidos no convite aberto pelo jogo (como o modo de jogo, por exemplo). Se a chamada for bem-sucedida, o último caractere da cadeira será o terminador nulo.
cchMetadata	uint32	O tamanho do buffer alocado para pchMetadata.

Recupera detalhes sobre o convite aberto especificado. Use a API ISteamFriends para recuperar detalhes sobre pSteamIDBeaconOwner, e a função ISteamParties::GetBeaconLocationData para recuperar detalhes sobre pLocation. O conteúdo de pchMetadata é definido pelo jogo e conterá o que foi definido (se houver algo definido) pelo processo do jogo que criou o convite aberto.

Retorna: bool

JoinParty

Nome	Tipo	Descrição
ulBeacon	PartyBeaconID_t	O ID do convite aberto que deseja seguir.

Quando o usuário indicar que deseja entrar em um grupo anunciado por um convite aberto, chame esta função. Em caso de sucesso, o Steam reservará uma vaga para o usuário no grupo e retornará a string de "entrada em partida" necessária para concluir a conexão.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada JoinParty_t.
Retorna k_uAPICallInvalid se o ID do convite aberto for inválido.

GetBeaconLocationData

Nome	Tipo	Descrição
BeaconLocation	SteamPartyBeaconLocation_t	O local a consultar.
eData	ESteamPartyBeaconLocationData	O tipo de dado do local que deseja recuperar.
pchDataStringOut	char *	O buffer de saída da string de dados do local. Se a chamada for bem-sucedida, o último caractere da cadeira será o terminador nulo.
cchDataStringOut	int	O tamanho do buffer alocado para pchDataStringOut.

Consulta metadados gerais para um dado local de convite aberto, como o nome ou URL de um ícone, se o tipo do local admite ícones (por exemplo, o ícone para uma sala de conversa no Steam).

Retorna: bool

Retornos de chamada

Estes são os retornos de chamada (callbacks) que podem ser disparados ao chamar SteamAPI_RunCallbacks. Muitos podem ser disparados diretamente em resposta às funções de membro de ISteamParties.

JoinPartyCallback_t

Usado como resposta a uma chamada à função ISteamParties::JoinParty. Se a chamada for bem-sucedida, uma vaga terá sido reservada para o usuário no grupo do dono do convite aberto, e o valor de m_rgchConnectString deve ser usado para conectar-se à partida e concluir o processo.

Nome	Tipo	Descrição
m_eResult	EResult	O resultado da tentativa de entrar no grupo.
m_ulBeaconID	PartyBeaconID_t	O ID do convite aberto usado na tentativa.
m_SteamIDBeaconOwner	CSteamID	O criador do convite aberto usado na tentativa.
m_rgchConnectString	char[256]	Se a chamada for bem-sucedida, conterá uma string de "entrada em partida" para o seu jogo concluir o processo de entrada no grupo desejado.

CreateBeaconCallback_t

Usado como resposta a uma chamada à função ISteamParties::CreateBeacon. Se a chamada for bem-sucedida, isso significa que o convite aberto foi publicado no local desejado e o jogo poderá começar a receber disparos de retornos de chamada do tipo ISteamParties::ReservationNotificationCallback_t para usuários que seguirem o convite aberto.

Nome	Tipo	Descrição
m_eResult	EResult	O resultado da tentativa de criar um convite aberto.
m_ulBeaconID	PartyBeaconID_t	O ID do convite aberto recém-criado.

ReservationNotificationCallback_t

Depois de criar um convite aberto, quando um usuário "seguir" o convite, o Steam disparará este retorno de chamada para avisar que você deve se preparar para o usuário entrar na partida. Quando o usuário de fato entrar, chame a função ISteamParties::OnReservationCompleted para avisar o Steam de que a entrada foi bem-sucedida.

Nome	Tipo	Descrição
m_ulBeaconID	PartyBeaconID_t	O ID do convite aberto.
m_steamIDJoiner	CSteamID	ID Steam do usuário que está seguindo o convite aberto.

ChangeNumOpenSlotsCallback_t

Call result for ISteamParties::ChangeNumOpenSlots.

Nome	Tipo	Descrição
m_eResult	EResult	O resultado da tentativa de alterar a quantidade de vagas abertas.

AvailableBeaconLocationsUpdated_t

Notificação de que a lista de locais disponíveis para publicação de convites abertos foi atualizada.

Este retorno de chamada não possui campos.

ActiveBeaconsUpdated_t

Notificação de que a lista de convites abertos ativos visíveis ao usuário atual foi alterada.

Este retorno de chamada não possui campos.

Structs

Estas são as structs com as quais funções da interface ISteamParties podem retornar e/ou interagir.

SteamPartyBeaconLocation_t

Nome	Tipo	Descrição
m_eType	ESteamPartyBeaconLocationType	O tipo do local.
m_ulLocationID	uint64	Identificador opaco do local.

Enumerações

Estas são as enumerações definidas para uso com ISteamParties.

ESteamPartyBeaconLocationType

Tipos de locais onde convites abertos podem ser publicados.

Nome	Valor	Descrição
k_ESteamPartyBeaconLocationType_Invalid	0	Tipo de local inválido.
k_ESteamPartyBeaconLocationType_ChatGroup	1	Uma sala de conversa no Steam.
k_ESteamPartyBeaconLocationType_Max		O valor deste campo será sempre o maior valor válido, mais um.

ESteamPartyBeaconLocationData

Tipos de metadados estendidos para locais de convites abertos.

Nome	Valor	Descrição
k_ESteamPartyBeaconLocationDataInvalid	0	Tipo de dado de local inválido.
k_ESteamPartyBeaconLocationDataName	1	O nome do local, se houver.
k_ESteamPartyBeaconLocationDataIconURLSmall		Se o local possuir um ícone associado, este é o URL para a imagem do ícone em formato pequeno.
k_ESteamPartyBeaconLocationDataIconURLMedium		Se o local possuir um ícone associado, este é o URL para a imagem do ícone em formato médio.
k_ESteamPartyBeaconLocationDataIconURLLarge		Se o local possuir um ícone associado, este é o URL para a imagem do ícone em formato grande.

Tipos definidos

Estes são os tipos definidos por typedefs para uso com ISteamParties.

Nome	Tipo base	Descrição
PartyBeaconID_t	uint64	Um handle para um convite aberto para grupo no Steam.