Functions which provide access to the game server browser.

See Game Servers for more information.

Member Functions

Member functions for ISteamMatchmakingServers are called through the global accessor function SteamMatchmakingServers().

CancelQuery

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.

Cancel an outstanding server list request.
You should call this to cancel any in-progress requests before destructing a callback object that may have been passed
to one of the below request calls. Not doing so may result in a crash when a callback occurs on the destructed object.
Canceling a query does not release the allocated request handle. The request handle must be released using ReleaseRequest.

CancelServerQuery

Name	Type	Description
hServerQuery	HServerQuery	The server query to cancel.

Cancel an outstanding individual server query.

The calls that create this type of query are:

• PingServer
  
• PlayerDetails
  
• ServerRules

You should call this to cancel any in-progress requests before destructing a callback object that may have been passed to one of the above calls to avoid crashing when callbacks occur.

GetServerCount

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.

Gets the number of servers in the given list.

This is used for iterating with GetServerDetails.

Returns: int
The number of servers in a server list request object.

Returns 0 if hRequest is invalid.

GetServerDetails

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.
iServer	int	The index of the server to get the details of, from 0 to GetServerCount.

Get the details of a given server in the list.

You can get the valid range of index values by calling GetServerCount.

You will also receive index values in ISteamMatchmakingServerListResponse::ServerResponded callbacks.

Returns: gameserveritem_t *

IsRefreshing

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.

Checks if the server list request is currently refreshing.

Returns: bool
true if hRequest is valid, and is currently refreshing; otherwise, false.

PingServer

Name	Type	Description
unIP	uint32	The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPort	uint16	The port of the game server you are querying, in host order.
pRequestServersResponse	ISteamMatchmakingPingResponse *	This must be the object that inherits from ISteamMatchmakingPingResponse. Typically this.

Queries an individual game servers directly via IP/Port to request an updated ping time and other details from the server.

You must inherit from the ISteamMatchmakingPingResponse object to receive this callback.

ISteamMatchmakingPingResponse

Callback interface for receiving responses after pinging an individual server.

If you are destructing an object that implements this interface then you should call CancelServerQuery passing in the handle to the query which is in progress. Failure to cancel in progress queries when destructing a callback handler may result in a crash when a callback later occurs.

Member functions:

Return type	Function name	Parameters	Description
void	ServerResponded	gameserveritem_t &server	Called when the server has responded successfully and has updated data.
void	ServerFailedToRespond		Called when the server failed to respond to the ping request.

Returns: HServerQuery
Handle to the outstanding server query.

PlayerDetails

Name	Type	Description
unIP	uint32	The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPort	uint16	The port of the game server you are querying, in host order.
pRequestServersResponse	ISteamMatchmakingPlayersResponse *	This must be the object that inherits from ISteamMatchmakingPlayersResponse. Typically this.

Queries an individual game servers directly via IP/Port to request the list of players currently playing on the server.

You must inherit from the ISteamMatchmakingPlayersResponse object to receive this callback.

ISteamMatchmakingPlayersResponse

Callback interface for receiving responses after pinging an individual server.

If you are destructing an object that implements this interface then you should call CancelServerQuery passing in the handle to the query which is in progress. Failure to cancel in progress queries when destructing a callback handler may result in a crash when a callback later occurs.

Member functions:

Return type	Function name	Parameters	Description
void	AddPlayerToList	const char *pchName, int nScore, float flTimePlayed	Called when we retrieved data on a new player on the server -- you'll get this callback once per player on the server which you have requested player data on.
void	PlayersFailedToRespond		Called when the server failed to respond to the request for player details.
void	PlayersRefreshComplete		Called when the server has finished responding to the player details request (ie, you won't get anymore AddPlayerToList callbacks)

Returns: HServerQuery
Handle to the outstanding server query.

RefreshQuery

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.

Ping every server in your list again but don't update the list of servers.

The query callback installed when the server list was requested will be used again to post notifications and RefreshComplete will be called again, so the callback must remain valid until it completes or the request is released with ReleaseRequest.

RefreshServer

Name	Type	Description
hRequest	HServerListRequest	The handle to the server list request.
iServer	int	The index of the server to refresh, from 0 to GetServerCount.

Refreshes a single server inside of a query.

If you want to refresh all of the servers then you should use RefreshQuery.

ReleaseRequest

Name	Type	Description
hServerListRequest	HServerListRequest	The asynchronous server list request object to release.

Releases the asynchronous server list request object and cancels any pending query on it if there's a pending query in progress.

The RefreshComplete callback will not be posted when request is released.

RequestFavoritesServerList

Name	Type	Description
iApp	AppId_t	The app to request the server list of.
ppchFilters	MatchMakingKeyValuePair_t **	An array of filters to only retrieve servers the user cares about.
nFilters	uint32	The number of filters in ppchFilters array.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'favorites' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

RequestFriendsServerList

Name	Type	Description
iApp	AppId_t	The app to request the server list of.
ppchFilters	MatchMakingKeyValuePair_t **	An array of filters to only retrieve servers the user cares about.
nFilters	uint32	The number of filters in ppchFilters array.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'friends' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

RequestHistoryServerList

Name	Type	Description
iApp	AppId_t	The app to get the server list of.
ppchFilters	MatchMakingKeyValuePair_t **	An array of filters to only retrieve servers the user cares about.
nFilters	uint32	The number of filters in ppchFilters array.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'history' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

RequestInternetServerList

Name	Type	Description
iApp	AppId_t	The app to get the server list of.
ppchFilters	MatchMakingKeyValuePair_t **	An array of filters to only retrieve servers the user cares about.
nFilters	uint32	The number of filters in ppchFilters array.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'internet' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
Triggers a LobbyChatUpdate_t callback.
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

RequestLANServerList

Name	Type	Description
iApp	AppId_t	The app to request the server list of.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'LAN' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

RequestSpectatorServerList

Name	Type	Description
iApp	AppId_t	The app to request the server list of.
ppchFilters	MatchMakingKeyValuePair_t **	An array of filters to only retrieve servers the user cares about.
nFilters	uint32	The number of filters in ppchFilters array.
pRequestServersResponse	ISteamMatchmakingServerListResponse *	This must be the object that inherits from ISteamMatchmakingServerListResponse. Typically this.

Request a new list of game servers from the 'spectator' server list.

See MatchMakingKeyValuePair_t for more information.

Returns: HServerListRequest
A new asynchronous server list request object.

NOTE: This request object must be released by calling ReleaseRequest when you're done using it!

ServerRules

Name	Type	Description
unIP	uint32	The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPort	uint16	The port of the game server you are querying, in host order.
pRequestServersResponse	ISteamMatchmakingRulesResponse *	This must be the object that inherits from ISteamMatchmakingRulesResponse. Typically this.

Queries an individual game servers directly via IP/Port to request the list of rules that the server is running. (See ISteamGameServer::SetKeyValue to set the rules on the server side.)

You must inherit from the ISteamMatchmakingRulesResponse object to receive this callback.

ISteamMatchmakingRulesResponse

Callback interface for receiving responses after pinging an individual server.

If you are destructing an object that implements this interface then you should call CancelServerQuery passing in the handle to the query which is in progress. Failure to cancel in progress queries when destructing a callback handler may result in a crash when a callback later occurs.

Member functions:

Return type	Function name	Parameters	Description
void	AddPlayerToList	const char *pchName, int nScore, float flTimePlayed	Called when we retrieved data on a rule on the server -- you'll get one of these per rule defined on the server you are querying.
void	PlayersFailedToRespond		Called when the server failed to respond to the request for rule details.
void	RulesRefreshComplete		Called when the server has finished responding to the rule details request (ie, you won't get anymore RulesResponded callbacks).

Returns: HServerQuery
Handle to the outstanding server query.

Structs

These are structs which functions in ISteamMatchmakingServers may return and/or interact with.

MatchMakingKeyValuePair_t

Store key/value pair used in matchmaking queries.

Actually, the name Key/Value is a bit misleading. The "key" is better understood as "filter operation code" and the "value" is the operand to this filter operation. The meaning of the operand depends upon the filter.

Supported filter operation codes:

• "map"
  Server passes the filter if the server is playing the specified map.
  
• "gamedataand"
  Server passes the filter if the server's game data (ISteamGameServer::SetGameData) contains all of the specified strings. The value field is a comma-delimited list of strings to match.
  
• "gamedataor"
  Server passes the filter if the server's game data (ISteamGameServer::SetGameData) contains at least one of the specified strings. The value field is a comma-delimited list of strings to match.
  
• "gamedatanor"
  Server passes the filter if the server's game data (ISteamGameServer::SetGameData) does not contain any of the specified strings. The value field is a comma-delimited list of strings to check.
  
• "gametagsand"
  Server passes the filter if the server's game tags (ISteamGameServer::SetGameTags) contains all of the specified strings. The value field is a comma-delimited list of strings to check.
  
• "gametagsnor"
  Server passes the filter if the server's game tags (ISteamGameServer::SetGameTags) does not contain any of the specified strings. The value field is a comma-delimited list of strings to check.
  
• "and" (x1 && x2 && ... && xn)
  "or" (x1 || x2 || ... || xn)
  "nand" !(x1 && x2 && ... && xn)
  "nor" !(x1 || x2 || ... || xn)
  Performs Boolean operation on the following filters. The operand to this filter specifies the "size" of the Boolean inputs to the operation, in Key/value pairs. (The keyvalue pairs must immediately follow, i.e. this is a prefix logical operator notation.) In the simplest case where Boolean expressions are not nested, this is simply the number of operands.
  For example, to match servers on a particular map or with a particular tag, would would use these filters.
  
  ( server.map == "cp_dustbowl" || server.gametags.contains("payload") ) "or", "2" "map", "cp_dustbowl" "gametagsand", "payload"
  
  If logical inputs are nested, then the operand specifies the size of the entire "length" of its operands, not the number of immediate children like so.
  
  ( server.map == "cp_dustbowl" || ( server.gametags.contains("payload") && !server.gametags.contains("payloadrace") ) ) "or", "4" "map", "cp_dustbowl" "and", "2" "gametagsand", "payload" "gametagsnor", "payloadrace"
  Unary NOT can be achieved using either "nand" or "nor" with a single operand.
  
  
• "addr"
  Server passes the filter if the server's query address matches the specified IP or IP:port.
  
• "gameaddr"
  Server passes the filter if the server's game address matches the specified IP or IP:port.

The following filter operations ignore the "value" part of MatchMakingKeyValuePair_t

• "dedicated"
  Server passes the filter if it passed true to ISteamGameServer::SetDedicatedServer.
  
• "secure"
  Server passes the filter if the server is VAC-enabled.
  
• "notfull"
  Server passes the filter if the player count is less than the reported max player count.
  
• "hasplayers"
  Server passes the filter if the player count is greater than zero.
  
• "noplayers"
  Server passes the filter if it doesn't have any players.
  
• "linux"
  Server passes the filter if it's a linux server.

Name	Type	Description
m_szKey	char［256］	Filter operation code.
m_szValue	char［256］	Operation operand.

Enums

These are enums which are defined for use with ISteamMatchmakingServers.

EMatchMakingServerResponse

Provided as the return response when refreshing Matchmaking Servers. See: RequestInternetServerList for more information.

Name	Value	Description
eServerResponded	0	The server responded successfully.
eServerFailedToRespond	1	The server failed to respond.
eNoServersListedOnMasterServer	2	Only for the internet query type, returned in response callback if no servers of this type match.

Constants

These are constants which are defined for use with ISteamMatchmakingServers.

Name	Type	Value	Description
k_cbMaxGameServerGameData	int	2048	The maximum size (in UTF-8 bytes, including the null terminator) supported for game server data which is set with ISteamGameServer::SetGameData.
k_cbMaxGameServerGameDescription	int	64	The maximum size (in UTF-8 bytes, including the null terminator) supported for the game server mod description which is set with ISteamGameServer::SetGameDescription.
k_cbMaxGameServerGameDir	int	32	The maximum size (in UTF-8 bytes, including the null terminator) supported for the game server mod dir which is set with ISteamGameServer::SetModDir.
k_cbMaxGameServerMapName	int	32	The maximum size (in UTF-8 bytes, including the null terminator) supported for game server map names which is set with ISteamGameServer::SetMapName.
k_cbMaxGameServerName	int	64	The maximum size (in UTF-8 bytes, including the null terminator) supported for game server names which is set with ISteamGameServer::SetServerName.
k_cbMaxGameServerTags	int	128	The maximum size (in UTF-8 bytes, including the null terminator) supported for game server tags which is set with ISteamGameServer::SetGameTags.