Documentação do Steamworks
Interface ISteamMatchmakingServers
Funções que oferecem acesso ao navegador de servidores.

Consulte Servidores de jogos para mais informações.

Funções de membro

Funções de membro de ISteamMatchmakingServers são chamadas por meio da função de acesso global SteamMatchmakingServers().

CancelQuery

void CancelQuery( HServerListRequest hRequest );
NomeTipoDescrição
hRequestHServerListRequestO handle da requisição da lista de servidores.

Cancela uma requisição pendente da lista de servidores.
Chame essa função para cancelar requisições em andamento antes de destruir um objeto de retorno de chamada passado a uma das chamadas para requisitar uma lista abaixo.
Não fazê-lo poderá resultar em um travamento quando um retorno de chamada for disparado com o objeto destruído.
Cancelar uma consulta não libera o handle da requisição alocado. O handle da requisição deve ser liberado por meio da função ReleaseRequest.

CancelServerQuery

void CancelServerQuery( HServerQuery hServerQuery );
NomeTipoDescrição
hServerQueryHServerQueryA consulta a servidor a cancelar.

Cancela uma consulta pendente a um servidor.

Chamadas que criam esse tipo de consulta:

Chame essa função para cancelar requisições em andamento antes de destruir um objeto de retorno de chamada que pode ter sido passado a uma das chamadas descritas acima para evitar travamentos quando retornos de chamada forem disparados.

GetServerCount

int GetServerCount( HServerListRequest hRequest );
NomeTipoDescrição
hRequestHServerListRequestO handle da requisição da lista de servidores.

Recupera a quantidade de servidores na lista informada.

Usada para iterar com a função GetServerDetails.

Retorna: int
A quantidade de servidores no objeto da requisição da lista de servidores.

Retorna 0 if hRequest for inválido.

GetServerDetails

gameserveritem_t * GetServerDetails( HServerListRequest hRequest, int iServer );
NomeTipoDescrição
hRequestHServerListRequestO handle da requisição da lista de servidores.
iServerintO índice do servidor cujos detalhes recuperar. Deve ser um valor entre 0 e GetServerCount, exclusive.

Recupera os detalhes de determinado servidor na lista.

Para recuperar o intervalo válido de valores, chame a função GetServerCount.

Você também receberá valores de índices por meio de retornos de chamada da função ISteamMatchmakingServerListResponse::ServerResponded.

Retorna: gameserveritem_t *

IsRefreshing

bool IsRefreshing( HServerListRequest hRequest );
NomeTipoDescrição
hRequestHServerListRequestO handle da solicitação da lista de servidores.

Verifica se a requisição da lista de servidores está em processo de atualização.

Retorna: bool
true se hRequest for válido e estiver em processo de atualização; false caso contrário.

PingServer

HServerQuery PingServer( uint32 unIP, uint16 usPort, ISteamMatchmakingPingResponse *pRequestServersResponse );
NomeTipoDescrição
unIPuint32O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001.
usPortuint16A porta do servidor a consultar, em ordem de host.
pRequestServersResponseISteamMatchmakingPingResponse *Deve ser o objeto que herda de ISteamMatchmakingPingResponse. Tipicamente this.

Consulta servidores individuais diretamente pelo endereço IP/porta para requisitar um ping e outros detalhes atualizados do servidor.

Você deverá herdar do objeto ISteamMatchmakingPingResponse para receber o retorno de chamada.

ISteamMatchmakingPingResponse

Interface de retorno de chamada para receber respostas depois de enviar um ping a um servidor individual.

Se estiver destruindo um objeto que implementa a interface, então chame a função CancelServerQuery, com o handle da consulta em andamento como parâmetro. Não cancelar consultas em andamento ao destruir uma função de tratamento de retorno de chamada pode resultar em um travamento quando o retorno de chamada for disparado.

Funções de membro:
Tipo de retornoNome da funçãoParâmetrosDescrição
voidServerRespondedgameserveritem_t &serverDisparado quando o servidor responder com sucesso e tiver dados atualizados.
voidServerFailedToRespondDisparado quando o servidor não responder à requisição de ping.

Retorna: HServerQuery
Handle da consulta de servidor pendente.

PlayerDetails

HServerQuery PlayerDetails( uint32 unIP, uint16 usPort, ISteamMatchmakingPlayersResponse *pRequestServersResponse );
NomeTipoDescrição
unIPuint32O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001.
usPortuint16A porta do servidor a consultar, em ordem de host.
pRequestServersResponseISteamMatchmakingPlayersResponse *Deve ser o objeto que herda de ISteamMatchmakingPlayersResponse. Tipicamente this.

Consulta servidores individuais diretamente diretamente pelo endereço IP/porta para requisitar a lista de jogadores conectados ao servidor.

Você deverá herdar do objeto ISteamMatchmakingPlayersResponse para receber o retorno de chamada.

ISteamMatchmakingPlayersResponse

Interface de retorno de chamada para receber respostas depois de enviar um ping a um servidor individual.

Se estiver destruindo um objeto que implementa a interface, então chame a função CancelServerQuery, com o handle da consulta em andamento como parâmetro. Não cancelar consultas em andamento ao destruir uma função de tratamento de retorno de chamada pode resultar em um travamento quando o retorno de chamada for disparado.

Funções de membro:
Tipo de retornoNome da funçãoParâmetrosDescrição
voidAddPlayerToListconst char *pchName, int nScore, float flTimePlayedDisparado ao receber dados de um jogador novo no servidor — o retorno de chamada será disparado uma vez por jogador no servidor cujos dados de jogadores requisitou.
voidPlayersFailedToRespondDisparado quando o servidor não responder à requisição de detalhes de jogadores.
voidPlayersRefreshCompleteDisparado quando o servidor terminar de responder à requisição de detalhes de jogadores (i.é., quando não receber mais retornos de chamada AddPlayerToList).

Retorna: HServerQuery
Handle da consulta de servidor pendente.

RefreshQuery

void RefreshQuery( HServerListRequest hRequest );
NomeTipoDescrição
hRequestHServerListRequestO handle da requisição da lista de servidores.

Envia um ping para cada servidor na lista, mas sem atualizá-la.

O retorno de chamada da consulta instalado no momento da solicitação da lista será usado novamente para disparar notificações e a função RefreshComplete será chamada novamente, então o retorno de chamada deve continuar válido até ser concluído ou a solicitação for liberada por meio da função ReleaseRequest.

RefreshServer

void RefreshServer( HServerListRequest hRequest, int iServer );
NomeTipoDescrição
hRequestHServerListRequestO handle da requisição da lista de servidores.
iServerintO índice do servidor a atualizar. Deve ser um valor entre 0 to GetServerCount, exclusive.

Atualiza um único servidor contido em uma consulta.

Se quiser atualizar todos os servidores, use a função RefreshQuery.

ReleaseRequest

void ReleaseRequest( HServerListRequest hServerListRequest );
NomeTipoDescrição
hServerListRequestHServerListRequestO objeto assíncrono da requisição da lista de servidores a liberar.

Libera o objeto assíncrono da requisição da lista de servidores e cancela qualquer consulta pendente que estiver em andamento.

O retorno de chamada RefreshComplete não será disparado quando a requisição for liberada.

RequestFavoritesServerList

HServerListRequest RequestFavoritesServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
ppchFiltersMatchMakingKeyValuePair_t **Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário.
nFiltersuint32A quantidade de filtros no vetor ppchFilters.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "favoritos".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

RequestFriendsServerList

HServerListRequest RequestFriendsServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
ppchFiltersMatchMakingKeyValuePair_t **Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário.
nFiltersuint32A quantidade de filtros no vetor ppchFilters.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "amigos".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

RequestHistoryServerList

HServerListRequest RequestHistoryServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
ppchFiltersMatchMakingKeyValuePair_t **Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário.
nFiltersuint32A quantidade de filtros no vetor ppchFilters.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "histórico".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

RequestInternetServerList

HServerListRequest RequestInternetServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
ppchFiltersMatchMakingKeyValuePair_t **Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário.
nFiltersuint32A quantidade de filtros no vetor ppchFilters.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "internet".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Dispara um retorno de chamada LobbyChatUpdate_t.
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

RequestLANServerList

HServerListRequest RequestLANServerList( AppId_t iApp, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "rede local (LAN)".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

RequestSpectatorServerList

HServerListRequest RequestSpectatorServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NomeTipoDescrição
iAppAppId_tO AppID cuja lista de servidores recuperar.
ppchFiltersMatchMakingKeyValuePair_t **Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário.
nFiltersuint32A quantidade de filtros no vetor ppchFilters.
pRequestServersResponseISteamMatchmakingServerListResponse *Deve ser o objeto que herda de ISteamMatchmakingServerListResponse. Tipicamente this.

Recupera uma lista nova de servidores na lista de servidores "espectador".

Consulte MatchMakingKeyValuePair_t para mais informações.

Retorna: HServerListRequest
Um novo objeto assíncrono da requisição da lista de servidores.

AVISO: o objeto da requisição deverá ser liberado por meio da função ReleaseRequest quando terminar de usá-lo!

ServerRules

HServerQuery ServerRules( uint32 unIP, uint16 usPort, ISteamMatchmakingRulesResponse *pRequestServersResponse );
NomeTipoDescrição
unIPuint32O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001.
usPortuint16A porta do servidor a consultar, em ordem de host.
pRequestServersResponseISteamMatchmakingRulesResponse *Deve ser o objeto que herda de ISteamMatchmakingRulesResponse. Tipicamente this.

Consulta servidores individuais diretamente pelo endereço IP/porta para requisitar a lista de regras usadas. (Consulte ISteamGameServer::SetKeyValue para definir as regras no lado do servidor.)

Você deverá herdar do objeto ISteamMatchmakingRulesResponse para receber o retorno de chamada.

ISteamMatchmakingRulesResponse

Interface de retorno de chamada para receber respostas depois de enviar um ping a um servidor individual.

Se estiver destruindo um objeto que implementa a interface, então chame a função CancelServerQuery, com o handle da consulta em andamento como parâmetro. Não cancelar consultas em andamento ao destruir uma função de tratamento de retorno de chamada pode resultar em um travamento quando o retorno de chamada for disparado.

Funções de membro:
Tipo de retornoNome da funçãoParâmetrosDescrição
voidAddPlayerToListconst char *pchName, int nScore, float flTimePlayedDisparado depois de recuperar os dados de uma regra do servidor — uma chamada por regra definida no servidor consultado.
voidPlayersFailedToRespondDisparado quando o servidor não responder à requisição de detalhes de regras.
voidRulesRefreshCompleteChamada quando o servidor terminar de responder à requisição de detalhes de regras (i.é., quando não receber mais retornos de respostas RulesResponded).

Retorna: HServerQuery
Handle da consulta de servidor pendente.

Structs

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

MatchMakingKeyValuePair_t

Armazena um par de chave e valor usado em consultas na criação de partidas.

Falar "chave e valor" não é uma boa explicação. A "chave" é melhor compreendida como "código de operação de filtragem" e o "valor" é o operando do filtro. O significado do operando depende do filtro.

Códigos de operação de filtragem disponíveis:
  • "map"
    O servidor entra no resultado se estiver hospedando o mapa especificado.
  • "gamedataand"
    O servidor entra no resultado se os dados da partida (ISteamGameServer::SetGameData) contiverem todas as strings especificadas. O campo de valor é uma lista separada por vírgulas das strings a verificar.
  • "gamedataor"
    O servidor entra no resultado se os dados da partida (ISteamGameServer::SetGameData) contiverem uma ou mais das strings especificadas. O campo de valor é uma lista separada por vírgulas das strings a verificar.
  • "gamedatanor"
    O servidor entra no resultado se os dados da partida (ISteamGameServer::SetGameData) contiverem nenhuma das strings especificadas. O campo de valor é uma lista separada por vírgulas das strings a verificar.
  • "gametagsand"
    O servidor entra no resultado se os marcadores do servidor (ISteamGameServer::SetGameTags) contiverem todas as strings especificadas. O campo de valor é uma lista separada por vírgulas das strings a verificar.
  • "gametagsnor"
    O servidor entra no resultado se os marcadores do servidor (ISteamGameServer::SetGameTags) contiverem nenhuma das strings especificadas. O campo de valor é uma lista separada por vírgulas das strings a verificar.
  • "and" (x1 && x2 && ... && xn)
    "or" (x1 || x2 || ... || xn)
    "nand" !(x1 && x2 && ... && xn)
    "nor" !(x1 || x2 || ... || xn)
    Realiza operação booleana nos filtros a seguir. O operando do filtro especifica o "tamanho" das entradas booleanas na operação, em pares de chave e valor (os pares devem seguir imediatamente, i.é., esta é uma notação de operadores lógicos prefixados). No caso mais simples, onde não há aninhamento de expressões booleanas, é simplesmente a quantidade de operandos.
    Por exemplo, para encontrar servidores com um mapa específico ou com um marcador específico, os filtros a seguir são usados.
    ( server.map == "cp_dustbowl" || server.gametags.contains("payload") ) "or", "2" "map", "cp_dustbowl" "gametagsand", "payload"

    Se houver entradas lógicas aninhadas, então o operando especifica o tamanho do "comprimento" total dos operandos, não a quantidade de filhos imediatos, como no exemplo a seguir:
    ( server.map == "cp_dustbowl" || ( server.gametags.contains("payload") && !server.gametags.contains("payloadrace") ) ) "or", "4" "map", "cp_dustbowl" "and", "2" "gametagsand", "payload" "gametagsnor", "payloadrace"
    NÃO é possível realizar uma operação unária por meio de "nand" ou "nor" com um único operando.

  • "addr"
    O servidor entra no resultado se o endereço de consulta do servidor for igual ao IP ou IP:porta especificado.
  • "gameaddr"
    O servidor entra no resultado se o endereço de partida do servidor for igual ao IP ou IP:porta especificado.

As operações de filtragem a seguir ignoram o campo "value" do callback MatchMakingKeyValuePair_t
  • "dedicated"
    O servidor entra no resultado se tiver passado o valor true para a função ISteamGameServer::SetDedicatedServer.
  • "secure"
    O servidor entra no resultado se for protegido por VAC.
  • "notfull"
    O servidor entra no resultado se a quantidade atual de jogadores for menor que a quantidade máxima de jogadores comunicada pelo servidor.
  • "hasplayers"
    O servidor entra no resultado se a quantidade atual de jogadores for maior que zero.
  • "noplayers"
    O servidor entra no resultado se não houver jogadores conectados.
  • "linux"
    O servidor entra no resultado se for um servidor Linux.

NomeTipoDescrição
m_szKeychar[256]Código da operação de filtragem.
m_szValuechar[256]Operando da operação.

Enumerações

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

EMatchMakingServerResponse

Retornado como resposta ao atualizar servidores de criações de partidas. Consulte RequestInternetServerList para mais informações.

NomeValorDescrição
eServerResponded0Servidor respondeu com sucesso.
eServerFailedToRespond1Servidor não respondeu.
eNoServersListedOnMasterServer2Apenas para o tipo de consulta "internet", retornado no retorno de resposta se não houver servidores do tipo.

Constantes

Estas são as constantes definidas para uso com ISteamMatchmakingServers.

NomeTipoValorDescrição
k_cbMaxGameServerGameDataint2048O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para dados do servidor, definidos pela função ISteamGameServer::SetGameData.
k_cbMaxGameServerGameDescriptionint64O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para a descrição da modificação do servidor, definida pela função ISteamGameServer::SetGameDescription.
k_cbMaxGameServerGameDirint32O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para o diretório da modificação do servidor, definido pela função ISteamGameServer::SetModDir.
k_cbMaxGameServerMapNameint32O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para o nome de mapas do servidor, definido pela função ISteamGameServer::SetMapName.
k_cbMaxGameServerNameint64O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para o nome de servidores, definido pela função ISteamGameServer::SetServerName.
k_cbMaxGameServerTagsint128O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para marcadores de servidores, definidos pela função ISteamGameServer::SetGameTags.