Steamworks Documentation
ISteamMatchmakingServers Interface
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

void CancelQuery( HServerListRequest hRequest );
NameTypeDescription
hRequestHServerListRequestThe 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

void CancelServerQuery( HServerQuery hServerQuery );
NameTypeDescription
hServerQueryHServerQueryThe server query to cancel.

Cancel an outstanding individual server query.

The calls that create this type of query are:

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

int GetServerCount( HServerListRequest hRequest );
NameTypeDescription
hRequestHServerListRequestThe 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

gameserveritem_t * GetServerDetails( HServerListRequest hRequest, int iServer );
NameTypeDescription
hRequestHServerListRequestThe handle to the server list request.
iServerintThe 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

bool IsRefreshing( HServerListRequest hRequest );
NameTypeDescription
hRequestHServerListRequestThe 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

HServerQuery PingServer( uint32 unIP, uint16 usPort, ISteamMatchmakingPingResponse *pRequestServersResponse );
NameTypeDescription
unIPuint32The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPortuint16The port of the game server you are querying, in host order.
pRequestServersResponseISteamMatchmakingPingResponse *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 typeFunction nameParametersDescription
voidServerRespondedgameserveritem_t &serverCalled when the server has responded successfully and has updated data.
voidServerFailedToRespondCalled when the server failed to respond to the ping request.

Returns: HServerQuery
Handle to the outstanding server query.

PlayerDetails

HServerQuery PlayerDetails( uint32 unIP, uint16 usPort, ISteamMatchmakingPlayersResponse *pRequestServersResponse );
NameTypeDescription
unIPuint32The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPortuint16The port of the game server you are querying, in host order.
pRequestServersResponseISteamMatchmakingPlayersResponse *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 typeFunction nameParametersDescription
voidAddPlayerToListconst char *pchName, int nScore, float flTimePlayedCalled 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.
voidPlayersFailedToRespondCalled when the server failed to respond to the request for player details.
voidPlayersRefreshCompleteCalled 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

void RefreshQuery( HServerListRequest hRequest );
NameTypeDescription
hRequestHServerListRequestThe 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

void RefreshServer( HServerListRequest hRequest, int iServer );
NameTypeDescription
hRequestHServerListRequestThe handle to the server list request.
iServerintThe 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

void ReleaseRequest( HServerListRequest hServerListRequest );
NameTypeDescription
hServerListRequestHServerListRequestThe 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

HServerListRequest RequestFavoritesServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to request the server list of.
ppchFiltersMatchMakingKeyValuePair_t **An array of filters to only retrieve servers the user cares about.
nFiltersuint32The number of filters in ppchFilters array.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerListRequest RequestFriendsServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to request the server list of.
ppchFiltersMatchMakingKeyValuePair_t **An array of filters to only retrieve servers the user cares about.
nFiltersuint32The number of filters in ppchFilters array.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerListRequest RequestHistoryServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to get the server list of.
ppchFiltersMatchMakingKeyValuePair_t **An array of filters to only retrieve servers the user cares about.
nFiltersuint32The number of filters in ppchFilters array.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerListRequest RequestInternetServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to get the server list of.
ppchFiltersMatchMakingKeyValuePair_t **An array of filters to only retrieve servers the user cares about.
nFiltersuint32The number of filters in ppchFilters array.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerListRequest RequestLANServerList( AppId_t iApp, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to request the server list of.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerListRequest RequestSpectatorServerList( AppId_t iApp, MatchMakingKeyValuePair_t **ppchFilters, uint32 nFilters, ISteamMatchmakingServerListResponse *pRequestServersResponse );
NameTypeDescription
iAppAppId_tThe app to request the server list of.
ppchFiltersMatchMakingKeyValuePair_t **An array of filters to only retrieve servers the user cares about.
nFiltersuint32The number of filters in ppchFilters array.
pRequestServersResponseISteamMatchmakingServerListResponse *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

HServerQuery ServerRules( uint32 unIP, uint16 usPort, ISteamMatchmakingRulesResponse *pRequestServersResponse );
NameTypeDescription
unIPuint32The IP of the game server you are querying in host order, i.e 127.0.0.1 == 0x7f000001.
usPortuint16The port of the game server you are querying, in host order.
pRequestServersResponseISteamMatchmakingRulesResponse *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 typeFunction nameParametersDescription
voidAddPlayerToListconst char *pchName, int nScore, float flTimePlayedCalled 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.
voidPlayersFailedToRespondCalled when the server failed to respond to the request for rule details.
voidRulesRefreshCompleteCalled 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.

NameTypeDescription
m_szKeychar[256]Filter operation code.
m_szValuechar[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.

NameValueDescription
eServerResponded0The server responded successfully.
eServerFailedToRespond1The server failed to respond.
eNoServersListedOnMasterServer2Only 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.

NameTypeValueDescription
k_cbMaxGameServerGameDataint2048The maximum size (in UTF-8 bytes, including the null terminator) supported for game server data which is set with ISteamGameServer::SetGameData.
k_cbMaxGameServerGameDescriptionint64The maximum size (in UTF-8 bytes, including the null terminator) supported for the game server mod description which is set with ISteamGameServer::SetGameDescription.
k_cbMaxGameServerGameDirint32The maximum size (in UTF-8 bytes, including the null terminator) supported for the game server mod dir which is set with ISteamGameServer::SetModDir.
k_cbMaxGameServerMapNameint32The maximum size (in UTF-8 bytes, including the null terminator) supported for game server map names which is set with ISteamGameServer::SetMapName.
k_cbMaxGameServerNameint64The maximum size (in UTF-8 bytes, including the null terminator) supported for game server names which is set with ISteamGameServer::SetServerName.
k_cbMaxGameServerTagsint128The maximum size (in UTF-8 bytes, including the null terminator) supported for game server tags which is set with ISteamGameServer::SetGameTags.