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 );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O 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 );
Nome | Tipo | Descrição |
hServerQuery | HServerQuery | A 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 );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O 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 );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O handle da requisição da lista de servidores. |
iServer | int | O í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 );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O 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 );
Nome | Tipo | Descrição |
unIP | uint32 | O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001. |
usPort | uint16 | A porta do servidor a consultar, em ordem de host. |
pRequestServersResponse | ISteamMatchmakingPingResponse * | 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 retorno | Nome da função | Parâmetros | Descrição |
void | ServerResponded | gameserveritem_t &server | Disparado quando o servidor responder com sucesso e tiver dados atualizados. |
void | ServerFailedToRespond | | Disparado quando o servidor não responder à requisição de ping. |
Retorna: HServerQueryHandle da consulta de servidor pendente.
PlayerDetails
HServerQuery PlayerDetails( uint32 unIP, uint16 usPort, ISteamMatchmakingPlayersResponse *pRequestServersResponse );
Nome | Tipo | Descrição |
unIP | uint32 | O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001. |
usPort | uint16 | A porta do servidor a consultar, em ordem de host. |
pRequestServersResponse | ISteamMatchmakingPlayersResponse * | 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 retorno | Nome da função | Parâmetros | Descrição |
void | AddPlayerToList | const char *pchName, int nScore, float flTimePlayed | Disparado 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. |
void | PlayersFailedToRespond | | Disparado quando o servidor não responder à requisição de detalhes de jogadores. |
void | PlayersRefreshComplete | | Disparado quando o servidor terminar de responder à requisição de detalhes de jogadores (i.é., quando não receber mais retornos de chamada AddPlayerToList). |
Retorna: HServerQueryHandle da consulta de servidor pendente.
RefreshQuery
void RefreshQuery( HServerListRequest hRequest );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O 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 );
Nome | Tipo | Descrição |
hRequest | HServerListRequest | O handle da requisição da lista de servidores. |
iServer | int | O í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 );
Nome | Tipo | Descrição |
hServerListRequest | HServerListRequest | O 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
ppchFilters | MatchMakingKeyValuePair_t ** | Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário. |
nFilters | uint32 | A quantidade de filtros no vetor ppchFilters . |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestUm 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
ppchFilters | MatchMakingKeyValuePair_t ** | Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário. |
nFilters | uint32 | A quantidade de filtros no vetor ppchFilters . |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestUm 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
ppchFilters | MatchMakingKeyValuePair_t ** | Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário. |
nFilters | uint32 | A quantidade de filtros no vetor ppchFilters . |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestUm 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
ppchFilters | MatchMakingKeyValuePair_t ** | Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário. |
nFilters | uint32 | A quantidade de filtros no vetor ppchFilters . |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestDispara 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestUm 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 );
Nome | Tipo | Descrição |
iApp | AppId_t | O AppID cuja lista de servidores recuperar. |
ppchFilters | MatchMakingKeyValuePair_t ** | Um vetor de filtros, para recuperar apenas os servidores de importância para o usuário. |
nFilters | uint32 | A quantidade de filtros no vetor ppchFilters . |
pRequestServersResponse | ISteamMatchmakingServerListResponse * | 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: HServerListRequestUm 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 );
Nome | Tipo | Descrição |
unIP | uint32 | O endereço IP do servidor a consultar, em ordem de host, i.é., 127.0.0.1 == 0x7f000001. |
usPort | uint16 | A porta do servidor a consultar, em ordem de host. |
pRequestServersResponse | ISteamMatchmakingRulesResponse * | 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 retorno | Nome da função | Parâmetros | Descrição |
void | AddPlayerToList | const char *pchName, int nScore, float flTimePlayed | Disparado depois de recuperar os dados de uma regra do servidor — uma chamada por regra definida no servidor consultado. |
void | PlayersFailedToRespond | | Disparado quando o servidor não responder à requisição de detalhes de regras. |
void | RulesRefreshComplete | | Chamada quando o servidor terminar de responder à requisição de detalhes de regras (i.é., quando não receber mais retornos de respostas RulesResponded). |
Retorna: HServerQueryHandle 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.
Nome | Tipo | Descrição |
m_szKey | char[256] | Código da operação de filtragem. |
m_szValue | char[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.
Nome | Valor | Descrição |
eServerResponded | 0 | Servidor respondeu com sucesso. |
eServerFailedToRespond | 1 | Servidor não respondeu. |
eNoServersListedOnMasterServer | 2 | Apenas 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.
Nome | Tipo | Valor | Descrição |
k_cbMaxGameServerGameData | int | 2048 | O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para dados do servidor, definidos pela função ISteamGameServer::SetGameData. |
k_cbMaxGameServerGameDescription | int | 64 | O 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_cbMaxGameServerGameDir | int | 32 | O 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_cbMaxGameServerMapName | int | 32 | O 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_cbMaxGameServerName | int | 64 | O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para o nome de servidores, definido pela função ISteamGameServer::SetServerName. |
k_cbMaxGameServerTags | int | 128 | O tamanho máximo (em bytes UTF-8, incluindo o terminador nulo) permitido para marcadores de servidores, definidos pela função ISteamGameServer::SetGameTags. |