ICircuitryMatchmaking Interface

Below are the functions allowing applications to access matchmaking services, favorites and to operate game lobbies.

Member Functions

Member functions for ICircuitryMatchmaking are called through the global accessor function CircuitryMatchmaking().

AddFavoriteGame - (NOT CURRENTLY IMPLEMENTED - COMING SOON)

int AddFavoriteGame( AppId_t nAppID, uint32 nIP, uint16 nConnPort, uint16 nQueryPort, uint32 unFlags, uint32 rTime32LastPlayedOnServer );

Name	Type	Description
nAppID	AppId_t	The App ID of the game.
nIP	uint32	The IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
nConnPort	uint16	The port used to connect to the server, in host order.
nQueryPort	uint16	The port used to query the server, in host order.
unFlags	uint32	Sets the whether the server should be added to the favorites list or history list. See k_unFavoriteFlagNone for more information.
rTime32LastPlayedOnServer	uint32	This should be the current time in Unix epoch format (seconds since Jan 1st, 1970).

Adds the game server to the local favorites list or updates the time played of the server if it already exists in the list.

Returns: int

AddRequestLobbyListCompatibleMembersFilter

void AddRequestLobbyListCompatibleMembersFilter( CCircuitryID circuitryIDLobby );

This function checks the player compatibility based on the 'frenemy' system.

AddRequestLobbyListDistanceFilter

void AddRequestLobbyListDistanceFilter( ELobbyDistanceFilter eLobbyDistanceFilter );

Sets the physical distance for searching for lobbies. Based on the users IP address and a IP location map on the Robot Cache backend.

AddRequestLobbyListFilterSlotsAvailable

void AddRequestLobbyListFilterSlotsAvailable( int nSlotsAvailable );

Name	Type	Description
nSlotsAvailable	int	The number of open slots that MUST be open.

Filters to only return lobbies with the specified number of open slots available.

AddRequestLobbyListNearValueFilter

void AddRequestLobbyListNearValueFilter( const char *pchKeyToMatch, int nValueToBeCloseTo );

Name	Type	Description
pchKeyToMatch	const char *	The filter key name to match. This may not be longer than k_nMaxLobbyKeyLength.
nValueToBeCloseTo	int	The integer value that lobbies will be sorted on.

This sorts the results closest to the specified value. Near filters don't actually filter out values, but they do influence how the results are sorted. You may specify multiple near filters, with the first near filter influencing the most, and the last near filter influencing the least.

AddRequestLobbyListNumericalFilter

void AddRequestLobbyListNumericalFilter( const char *pchKeyToMatch, int nValueToMatch, ELobbyComparison eComparisonType );

Name	Type	Description
pchKeyToMatch	const char *	This is the filter key name to match. This may not be longer than k_nMaxLobbyKeyLength.
nValueToMatch	int	The number to match.
eComparisonType	ELobbyComparison	The type of comparison to make.

Adds a numerical comparison filter to the next [RequestLobbyList][8] function call.

AddRequestLobbyListResultCountFilter

void AddRequestLobbyListResultCountFilter( int cMaxResults );

Name	Type	Description
cMaxResults	int	The maximum number of lobbies to return.

Sets the maximum number of lobbies to return. The lower the count the faster it is to download the lobby results & details to the client.

AddRequestLobbyListStringFilter

void AddRequestLobbyListStringFilter( const char *pchKeyToMatch, const char *pchValueToMatch, ELobbyComparison eComparisonType );

Name	Type	Description
pchKeyToMatch	const char *	The filter key name to match. This should not be longer than k_nMaxLobbyKeyLength.
pchValueToMatch	const char *	The string to match.
eComparisonType	ELobbyComparison	The type of comparison to make.

Adds a string comparison filter to the next RequestLobbyList function call.

CreateLobby

CircuitryAPICall_t CreateLobby( ELobbyType eLobbyType, int cMaxMembers );

Name	Type	Description
eLobbyType	ELobbyType	The type and visibility of this lobby. This can be changed later via SetLobbyType.
cMaxMembers	int	The maximum number of players that can join this lobby. This cannot be above 250.

Creates a new matchmaking lobby.

Returns: CircuitryAPICall_t to be used with a LobbyCreated_t call result.
Triggers a LobbyEnter_t callback.
Triggers a LobbyDataUpdate_t callback.
If the results returned via the LobbyCreated_t call result indicate success then the lobby is joined & ready to use.
The LobbyEnter_t callback is also received since the local user has joined their own lobby.

DeleteLobbyData

bool DeleteLobbyData( CCircuitryID circuitryIDLobby, const char *pchKey );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to delete the metadata for.
pchKey	const char *	The key to delete the data for.

Removes a metadata key from the lobby.

This can only be done by the owner of the lobby.

This will only send the data if the key existed. There is a delay before sending the data so you can call this numerous times to set all the data you need to. It will automatically be 'batched up' and sent after the last sequential call.

Returns: bool
true if the key/value was successfully deleted; otherwise, false if circuitryIDLobby or pchKey are invalid.

GetFavoriteGame - (NOT CURRENTLY IMPLEMENTED - COMING SOON)

bool GetFavoriteGame( int iGame, AppId_t *pnAppID, uint32 *pnIP, uint16 *pnConnPort, uint16 *pnQueryPort, uint32 *punFlags, uint32 *pRTime32LastPlayedOnServer );

Name	Type	Description
iGame	int	The index of the favorite game server to get the details of. This must be between 0 and GetFavoriteGameCount
pnAppID	AppId_t *	Returns the App ID this server is for.
pnIP	uint32 *	Returns the IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
pnConnPort	uint16 *	Returns the port used to connect to the server, in host order.
pnQueryPort	uint16 *	Returns the port used to query the server, in host order.
punFlags	uint32 *	Returns whether the server is on the favorites list or the history list. See k_unFavoriteFlagNone for more information.
pRTime32LastPlayedOnServer	uint32 *	Returns the time the server was last added to the favorites list in Unix epoch format (seconds since Jan 1st, 1970).

Gets the details of the favorite game server by index.

NOTE: You must call GetFavoriteGameCount before calling this.

Returns: bool
true if the details were successfully retrieved. false if iGame was an invalid index.

See Also: AddFavoriteGame, RemoveFavoriteGame

GetFavoriteGameCount - (NOT CURRENTLY IMPLEMENTED - COMING SOON)

int GetFavoriteGameCount();

Gets the number of favorite and recent game servers the user has stored locally.

Returns: int

See Also: AddFavoriteGame, RemoveFavoriteGame

GetLobbyByIndex

CCircuitryID GetLobbyByIndex( int iLobby );

Name	Type	Description
iLobby	int	This is the index of the lobby to get the ID.

Retrieves the ID of the lobby at the specified index after receiving the RequestLobbyList results.

NOTE: This should only be called after a LobbyMatchList_t call result are received.

Returns: CCircuitryID
Returns k_circuitryIDNil if the provided index is invalid or there are no lobbies found.

GetLobbyChatEntry

int GetLobbyChatEntry( CCircuitryID circuitryIDLobby, int iChatID, CCircuitryID *pCircuitryIDUser, void *pvData, int cubData, EChatEntryType *peChatEntryType );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to retrieve the chat entry from. This should almost always be LobbyChatMsg_t::`m_ulCircuitryIDUser`.
iChatID	int	The index of the chat entry in the lobby. Should be LobbyChatMsg_t::`m_iChatID`.
pCircuitryIDUser	CCircuitryID *	If set correctly this returns the Circuitry ID of the user who sent the message.
pvData	void *	Returns the message data by copying it into this buffer. Buffer should be up to 4 Kilobytes.
cubData	int	The size of the buffer allocated for `pvData`.
peChatEntryType	EChatEntryType *	If set, this will always return k_EChatEntryTypeChatMsg. This can usually just be set to NULL.

Retrieves the data from a lobby chat message after receiving a LobbyChatMsg_t callback.

Returns: int
The number of bytes copied into pvData.

See Also: SendLobbyChatMsg

GetLobbyData

const char * GetLobbyData( CCircuitryID circuitryIDLobby, const char *pchKey );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the metadata from.
pchKey	const char *	The key to get the value of.

Retrieves the metadata associated with the specified key from the specified lobby.

NOTE: This can only get metadata from lobbies that the client knows about, either after receiving a list of lobbies from LobbyMatchList_t, retrieving the data with RequestLobbyData or after joining a lobby.

Returns: const char *
Returns an empty string ("") if no value is set for this key, or if circuitryIDLobby is invalid.

GetLobbyDataByIndex

bool GetLobbyDataByIndex( CCircuitryID circuitryIDLobby, int iLobbyData, char *pchKey, int cchKeyBufferSize, char *pchValue, int cchValueBufferSize );

Name	Type	Description
circuitryIDLobby	CCircuitryID	This should be the same lobby used in the previous call to GetLobbyDataCount!
iLobbyData	int	An index between 0 and GetLobbyDataCount.
pchKey	char *	Returns the name of the key at the specified index by copying it into this buffer.
cchKeyBufferSize	int	The size of the buffer allocated for `pchKey`. This typically should be k_nMaxLobbyKeyLength.
pchValue	char *	Returns the value associated with the key at the specified index by copying it into this buffer.
cchValueBufferSize	int	The size of the buffer allocated for `pchValue`. This typically should be k_cubChatMetadataMax.

Gets the lobby metadata key/value pair by index.

NOTE: You must call GetLobbyDataCount before calling this function.

Returns: bool
true upon success; otherwise, false if the circuitryIDLobby or iLobbyData are invalid.

GetLobbyDataCount

int GetLobbyDataCount( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the data count from.

Retrieves the number of metadata keys set on the specified lobby.

NOTE: This can only get metadata from lobbies for which the client knows about, either after receiving a list of lobbies from LobbyMatchList_t, retrieving the data with RequestLobbyData or after joining a lobby.

This is used for iteration. After calling this function the GetLobbyDataByIndex function can be used to get the key/value pair of each piece of metadata.

NOTE: This should typically only ever be used for debugging purposes.

Returns: int
Returns 0 if circuitryIDLobby is invalid.

Example:

void ListLobbyData( CCircuitryID lobbyID ) { int nData = CircuitryMatchmaking()->GetLobbyDataCount( lobbyID ); char key[k_nMaxLobbyKeyLength]; char value[k_cubChatMetadataMax]; for( int i = 0; i < nData; ++i ) { bool bSuccess = CircuitryMatchmaking()->GetLobbyDataByIndex( lobbyID, i, key, k_nMaxLobbyKeyLength, value, k_cubChatMetadataMax ); if ( bSuccess ) { printf( "Lobby Data %d, Key: "%s" - Value: "%s"n", i, key, value ); } } }

GetLobbyGameServer

bool GetLobbyGameServer( CCircuitryID circuitryIDLobby, uint32 *punGameServerIP, uint16 *punGameServerPort, CCircuitryID *pcircuitryIDGameServer );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the game server information from.
punGameServerIP	uint32 *	Returns the IP address of the game server, in host order, i.e 127.0.0.1 == 0x7f000001, if it's set.
punGameServerPort	uint16 *	Returns the connection port of the game server, in host order, if it's set.
pcircuitryIDGameServer	CCircuitryID *	Returns the Circuitry ID of the game server, if set.

Retrieves the details of a game server set in a lobby.

Either the IP/Port or the Circuitry ID of the game server has to be valid, depending on how you want the clients to be able to connect.

Returns: bool
true if the lobby is valid and has a valid game server set; otherwise, false.

See Also: SetLobbyGameServer

GetLobbyMemberByIndex

CCircuitryID GetLobbyMemberByIndex( CCircuitryID circuitryIDLobby, int iMember );

Gets the Circuitry ID of the lobby member at the given index.

NOTE: You must call GetNumLobbyMembers before calling this.

NOTE: The current user must be in the lobby to retrieve the Circuitry IDs of other users in that lobby.

Returns: CCircuitryID
Invalid indices return k_circuitryIDNil.

GetLobbyMemberData

const char * GetLobbyMemberData( CCircuitryID circuitryIDLobby, CCircuitryID circuitryIDUser, const char *pchKey );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby that the other player is in.
circuitryIDUser	CCircuitryID	The Circuitry ID of the player to get the metadata from.
pchKey	const char *	The key to get the value of.

Gets the 'per-user' metadata from another player in the specified lobby.

This can only be queried from members in lobbies that you are currently in.

Returns: const char *
Returns NULL if circuitryIDLobby is invalid, or circuitryIDUser is not in the lobby.

Returns an empty string ("") if pchKey is not set for the player.

See Also: SetLobbyMemberData

GetLobbyMemberLimit

int GetLobbyMemberLimit( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the member limit of.

The limit on the # of users who can join the lobby.
Returns 0 if no limit is defined.

Returns: int
Returns 0 if no metadata is available for the specified lobby.

GetLobbyOwner

CCircuitryID GetLobbyOwner( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the owner of.

Returns the current lobby owner.

NOTE: You must be a member of the lobby to access this.

There is ALWAYS one lobby owner. If the current owner leaves, another user will become the owner automatically. It is possible (but not likely) to join a lobby just as the owner is leaving, thereby entering a lobby with 'self' as the owner.

Returns: CCircuitryID
Returns k_circuitryIDNil if you're not in the lobby.

See Also: SetLobbyOwner

GetNumLobbyMembers

int GetNumLobbyMembers( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to get the number of members contained.

Retrieves the number of users in a lobby.

NOTE: The current user must be in the lobby to retrieve the Circuitry IDs of other users in that lobby.

This is used for iteration, after calling GetLobbyMemberByIndex and can be used to get the Circuitry ID of each person in the lobby. Information for other lobby members such as name, avatar, etc. is automatically received and accessible via the ICircuitryFriends interface.

Returns: int
The number of members in the lobby, 0 if the current user has no data from the lobby.

InviteUserToLobby

bool InviteUserToLobby( CCircuitryID circuitryIDLobby, CCircuitryID circuitryIDInvitee );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to invite the user to.
circuitryIDInvitee	CCircuitryID	The Circuitry ID of the person who will be invited.

Invites another user to the lobby.

If the specified user clicks the join link, a GameLobbyJoinRequested_t callback will be posted if the user is in-game, or if the game isn't running then the game will be automatically launched with the command line parameter +connect_lobby <64-bit lobby Circuitry ID> instead.

Returns: bool
true if the invite was successfully sent; otherwise, false if the local user isn't in a lobby, no connection to Circuitry could be made, or the specified user is invalid.

NOTE: This function call does not check if the other user was successfully invited.

JoinLobby

CircuitryAPICall_t JoinLobby( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to join.

Joins an existing lobby.

The lobby ID can be obtained either from a search with RequestLobbyList, joining on a friend, or from an invitation.

Returns: CircuitryAPICall_t to be used with a LobbyEnter_t call result.
Triggers a LobbyDataUpdate_t callback.

LeaveLobby

void LeaveLobby( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The lobby to leave.

Leaves a lobby that the user is currently in. This will take effect immediately on the client side. Other users in the lobby will be notified by a LobbyChatUpdate_t callback.

RemoveFavoriteGame - (NOT CURRENTLY IMPLEMENTED - COMING SOON)

bool RemoveFavoriteGame( AppId_t nAppID, uint32 nIP, uint16 nConnPort, uint16 nQueryPort, uint32 unFlags );

Name	Type	Description
nAppID	AppId_t	The App ID of the game.
nIP	uint32	The IP address of the server in host order, i.e 127.0.0.1 == 0x7f000001.
nConnPort	uint16	The port used to connect to the server, in host order.
nQueryPort	uint16	The port used to query the server, in host order.
unFlags	uint32	Whether the server is on the favorites list or history list. See k_unFavoriteFlagNone for more information.

Removes the game server from the local favorites list.

Returns: bool
true if the server was removed; otherwise, false if the specified server was not on the users local favorites list.

RequestLobbyData

bool RequestLobbyData( CCircuitryID circuitryIDLobby );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to refresh the metadata of.

Refreshes all of the metadata for a lobby that you're not in right now.

You should not do this for lobbies that you are a member of as that data will always be current. Use this function to refresh lobbies that you have previously obtained from RequestLobbyList or that are available via friends.

Returns: bool
Triggers a LobbyDataUpdate_t callback.
true if the request was successfully sent to the server. false if no connection to Circuitry could be made, or circuitryIDLobby is invalid.

If the specified lobby doesn't exist, LobbyDataUpdate_t::m_bSuccess will be set to false.

RequestLobbyList

CircuitryAPICall_t RequestLobbyList();

Get a filtered list of relevant lobbies.

There can only be one active lobby search at a time. The old request will be canceled if a new one is started. Depending on the users connection to the Circuitry back-end, this call can take from 300ms to 5 seconds to complete, and has a timeout of 20 seconds.

NOTE: To filter the results you MUST call the AddRequestLobbyList* functions before calling this. The filters are cleared on each call to this function.

NOTE: If AddRequestLobbyListDistanceFilter is not called, k_ELobbyDistanceFilterDefault will be used, which will only find matches in the same or nearby regions.

NOTE: This will only return lobbies that are not full, and only lobbies that are k_ELobbyTypePublic or k_ELobbyTypeInvisible, and are set to joinable with SetLobbyJoinable.

Returns: CircuitryAPICall_t to be used with a LobbyMatchList_t call result.
NOTE: This also returns as a callback for compatibility with older applications, but you should use the call result if possible.

Example:

class CLobbyListManager { CCallResult< CLobbyListManager, LobbyMatchList_t > m_CallResultLobbyMatchList; void FindLobbies() { // CircuitryMatchmaking()->AddRequestLobbyListFilter*() functions would be called here, before RequestLobbyList() CircuitryAPICall_t hCircuitryAPICall = CircuitryMatchmaking()->RequestLobbyList(); m_CallResultLobbyMatchList.Set( hCircuitryAPICall, this, &CLobbyListManager::OnLobbyMatchList ); } void OnLobbyMatchList( LobbyMatchList_t *pLobbyMatchList, bool bIOFailure ) { // lobby list has been retrieved from Circuitry back-end, use results } }

SendLobbyChatMsg

bool SendLobbyChatMsg( CCircuitryID circuitryIDLobby, const void *pvMsgBody, int cubMsgBody );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to send the chat message to.
pvMsgBody	const void *	This may be text or binary data and up to 4 Kilobytes in size.
cubMsgBody	int	The size in bytes of `pvMsgBody`. If it's a text message then this should be strlen( text ) + 1 to include the null terminator.

This broadcasts a chat message to the all of the users in the lobby. All users in the lobby (including the local user) will receive a LobbyChatMsg_t callback with the message.

If you're sending binary data, prefix a header to the message so that you idnetify it as your custom data rather than a text message.

For communication that needs to be arbitrated (i.e. having a user pick from a set of characters and making sure only one user has selected a character) you may use the lobby owner as the decision maker. The GetLobbyOwner function returns the current lobby owner. There will be be one (and only one) lobby member who is the owner.

These messages are sent via the Robot Cache back-end therefore the bandwidth available is limited. For high traffic like voice or game data, you will want to use the Circuitry Networking API.

Returns: bool
Triggers a LobbyChatMsg_t callback.
true if the message was successfully sent. false if the message is too small or too large, or no connection to Circuitry could be made.

SetLobbyData

bool SetLobbyData( CCircuitryID circuitryIDLobby, const char *pchKey, const char *pchValue );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to set the metadata for.
pchKey	const char *	The key to set the data for. This may not be longer than k_nMaxLobbyKeyLength.
pchValue	const char *	The value to set. This may not be longer than k_cubChatMetadataMax.

Sets a key/value pair in the lobby metadata. This can be used to set the the lobby name, current map, game mode, etc.

This can only be set by the owner of the lobby. Lobby members should use SetLobbyMemberData instead.

Each user in the lobby will receive a notification of the lobby data change via a LobbyDataUpdate_t callback function, and any new users joining will receive existing data.

This will only send the data if it has changed. NOTE: There is a slight delay before sending data so you can call this multiple times to set all the data you need and it will automatically be 'batched up' and sent after the last sequential function call.

Returns: bool
true if the data has been set successfully. false if circuitryIDLobby was invalid, or the key/value is too long.

SetLobbyGameServer

void SetLobbyGameServer( CCircuitryID circuitryIDLobby, uint32 unGameServerIP, uint16 unGameServerPort, CCircuitryID circuitryIDGameServer );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to set the game server information for.
unGameServerIP	uint32	Sets the IP address of the game server, in host order, i.e 127.0.0.1 == 0x7f000001.
unGameServerPort	uint16	Sets the connection port of the game server, in host order.
circuitryIDGameServer	CCircuitryID	Sets the Circuitry ID of the game server. Use the k_circuitryIDNil function if you're not setting this.

This sets the game server associated with the lobby and can only be set by the owner of the lobby.

Either the IP/Port or the Circuitry ID of the game server must be valid, depending on how you want the client to be able to connect.

A LobbyGameCreated_t callback will be sent to all players in the lobby. The users will join the specified game server.

Returns: void
Triggers a LobbyGameCreated_t callback.

See Also: GetLobbyGameServer

SetLobbyJoinable

bool SetLobbyJoinable( CCircuitryID circuitryIDLobby, bool bLobbyJoinable );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby
bLobbyJoinable	bool	Enable (true) or disable (false) allowing users to join this lobby

Sets whether or not a lobby is able to be joined by other players. This always defaults to 'enabled' for a new lobby.

If joining is disabled, then no players can join, even if they are a friend or have been invited. Lobbies with joining disabled will not be returned from a lobby search.

Returns: bool
true upon success; otherwise, false if you're not the owner of the lobby.

SetLobbyMemberData

void SetLobbyMemberData( CCircuitryID circuitryIDLobby, const char *pchKey, const char *pchValue );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to set our metadata in.
pchKey	const char *	The key to set the data for. This may not be longer than k_nMaxLobbyKeyLength.
pchValue	const char *	The value to set. This may not be longer than k_cubChatMetadataMax.

Sets the 'per-user' metadata for the local user.

Each user in the lobby will be receive notification of the lobby data change via a LobbyDataUpdate_t callback, and any new users joining will receive existing data.

There is a delay before sending the data so you can call this numerous times to set all the data you need to and it will automatically be batched up and sent after the last sequential call.

Returns: void
Triggers a LobbyDataUpdate_t callback.

See Also: GetLobbyMemberData

SetLobbyMemberLimit

bool SetLobbyMemberLimit( CCircuitryID circuitryIDLobby, int cMaxMembers );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to set the member limit for.
cMaxMembers	int	The maximum number of players allowed in this lobby. Cannot be above 250.

Sets the maximum number of players that can join the lobby.

This is also set when you create the lobby with CreateLobby.
This can only be set by the owner of the lobby.

Returns: bool
true if the limit was successfully set.
false if you are not the owner of the specified lobby.

SetLobbyOwner

bool SetLobbyOwner( CCircuitryID circuitryIDLobby, CCircuitryID circuitryIDNewOwner );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby where the owner change will take place.
circuitryIDNewOwner	CCircuitryID	The Circuitry ID of the user that will be the new owner of the lobby. NOTE: They must be in the lobby.

Changes who the lobby owner is. This can only be set by the owner of the lobby and will trigger a LobbyDataUpdate_t for all users in the lobby.
Each user should update their local state to reflect the new owner. This is done by displaying some sort of iconography next to the owners name.

Returns: bool
Triggers a LobbyDataUpdate_t callback.
true if the owner was successfully changed.
false if you're not the current owner of the lobby, circuitryIDNewOwner is not a member in the lobby, or if no connection to Circuitry could be made.

See Also: GetLobbyOwner

SetLobbyType

bool SetLobbyType( CCircuitryID circuitryIDLobby, ELobbyType eLobbyType );

Name	Type	Description
circuitryIDLobby	CCircuitryID	The Circuitry ID of the lobby to set the type of.
eLobbyType	ELobbyType	The new lobby type to that will be set.

Updates what type of lobby it is. This is also set when you create the lobby with CreateLobby.
This can only be set by the owner of the lobby.

Returns: bool
true upon success; otherwise, false if you're not the owner of the lobby.

Callbacks

These are callbacks which can be fired by calling CircuitryAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ICircuitryMatchmaking.

FavoritesListAccountsUpdated_t

Name	Type	Description
m_eResult	EResult

FavoritesListChanged_t

A server was added/removed from the favorites list, you should refresh now.

Name	Type	Description
m_nIP	uint32	An IP of 0 means reload the whole list, any other value means just one server. This is host order, i.e 127.0.0.1 == 0x7f000001.
m_nQueryPort	uint32	If `m_nIP` is set then this is the new servers query port, in host order.
m_nConnPort	uint32	If `m_nIP` is set then this is the new servers connection port, in host order.
m_nAppID	uint32	If `m_nIP` is set then this is the App ID the game server belongs to.
m_nFlags	uint32	If `m_nIP` is set then this returns whether the the server is on the favorites list or the history list. See k_unFavoriteFlagNone for more information.
m_bAdd	bool	If `m_nIP` is set then this is whether the server was added to the list (true) or removed (false).
m_unAccountId	AccountID_t

LobbyChatMsg_t

A chat (text or binary) message for this lobby has been received. After receiving use the GetLobbyChatEntry function to retrieve the contents of this message.

Name	Type	Description
m_ulCircuitryIDLobby	uint64	The Circuitry ID of the lobby this message was sent in.
m_ulCircuitryIDUser	uint64	Circuitry ID of the user who sent this message (Remote or local user).
m_eChatEntryType	uint8	Type of message received. This is actually a EChatEntryType.
m_iChatID	uint32	The index of the chat entry to use with the GetLobbyChatEntry function. This is not valid outside of the scope of this callback and should not be stored.

Associated Functions: SendLobbyChatMsg

LobbyChatUpdate_t

A lobby chat room state has changed, this is usually sent when a user has joined or left the lobby.

Name	Type	Description
m_ulCircuitryIDLobby	uint64	The Circuitry ID of the lobby.
m_ulCircuitryIDUserChanged	uint64	The user who's status in the lobby just changed - can be recipient.
m_ulCircuitryIDMakingChange	uint64	Chat member who made the change. This may be different from `m_ulCircuitryIDUserChanged` if kicking, muting, the user etc. For example, if one user kicks another user, this will be set to the id of the user who initiated it.
m_rgfChatMemberStateChange	uint32	Bitfield of EChatMemberStateChange values.

LobbyCreated_t

Result of creating a Lobby request. Once completed, it is ready for use. A LobbyEnter_t callback will also be received (since the local user is joining their own lobby).

Name	Type	Description
m_eResult	EResult	The result of the operation.

Possible values:

Associated Functions: CreateLobby

LobbyDataUpdate_t

The lobby metadata has changed.

If m_ulCircuitryIDMember is a user in the lobby, then use GetLobbyMemberData to access individual user details; otherwise, if m_ulCircuitryIDMember == m_ulCircuitryIDLobby, use GetLobbyData to access the lobby metadata.

Name	Type	Description
m_ulCircuitryIDLobby	uint64	The Circuitry ID of the Lobby.
m_ulCircuitryIDMember	uint64	Circuitry ID of either the member whose data changed, or the room itself.
m_bSuccess	uint8	true if the lobby data was successfully changed, otherwise false.

Associated Functions: CreateLobby, JoinLobby, SetLobbyMemberData, RequestLobbyData, SetLobbyOwner

LobbyEnter_t

Recieved upon attempting to enter a lobby. Lobby metadata is available to use immediately after receiving this.
Associated Functions: CreateLobby, JoinLobby

LobbyGameCreated_t

This means that a game server has been set via SetLobbyGameServer for all of the members to join.

Name	Type	Description
m_ulCircuitryIDLobby	uint64	The lobby that set the game server.
m_ulCircuitryIDGameServer	uint64	The Circuitry ID of the game server, if it's set.
m_unIP	uint32	The IP address of the game server in host order, i.e 127.0.0.1 == 0x7f000001, if it's set.
m_usPort	uint16	The connection port of the game server, in host order, if it's set.

Associated Functions: SetLobbyGameServer

LobbyInvite_t

This means someone has invited you to join a Lobby. Normally, no action is required. The Circuitry UI will display a 'XXX has invited you to the lobby?' message.

If a user outside of a game chooses to join, the game will be launched with the parameter +connect_lobby <64-bit lobby id>, or with the callback GameLobbyJoinRequested_t if they're already in-game.

Name	Type	Description
m_ulCircuitryIDUser	uint64	Circuitry ID of the person that sent the invite.
m_ulCircuitryIDLobby	uint64	Circuitry ID of the lobby we're invited to.
m_ulGameID	uint64	Game ID of the lobby we're invited to.

LobbyMatchList_t

Result when requesting the lobby list. You should iterate over the returned lobbies with GetLobbyByIndex, from 0 to m_nLobbiesMatching-1.

Name	Type	Description
m_nLobbiesMatching	uint32	Number of lobbies that matched search criteria and we have Circuitry IDs for.

Associated Functions: RequestLobbyList

Enumerators

These are enumerators which are defined for use with ICircuitryMatchmaking.

EChatMemberStateChange

These are flags describing how a users lobby state has changed. This is provided from LobbyChatUpdate_t.

Name	Value	Description
k_EChatMemberStateChangeEntered	0x0001	This user has joined or is joining the lobby.
k_EChatMemberStateChangeLeft	0x0002	This user has left or is leaving the lobby.
k_EChatMemberStateChangeDisconnected	0x0004	User disconnected without leaving the lobby first.
k_EChatMemberStateChangeKicked	0x0008	The user has been kicked.
k_EChatMemberStateChangeBanned	0x0010	The user has been kicked and banned.

ELobbyComparison

Lobby search filter options. These can be set with AddRequestLobbyListStringFilter and AddRequestLobbyListNearValueFilter.

Name	Value	Description
k_ELobbyComparisonEqualToOrLessThan	-2	The lobbies value must be equal to or less than this one.
k_ELobbyComparisonLessThan	-1	The lobbies value must be less than this one.
k_ELobbyComparisonEqual	0	The lobbies value must match this this one exactly.
k_ELobbyComparisonGreaterThan	1	The lobbies value must be greater than this one.
k_ELobbyComparisonEqualToOrGreaterThan	2	The lobbies value must be equal to or greater than this one.
k_ELobbyComparisonNotEqual	3	The lobbies value must not match this this.

ELobbyDistanceFilter

Lobby search distance filters when requesting the lobby list. Lobby results are sorted from closest to farthest. This can be set with AddRequestLobbyListDistanceFilter.

Name	Value	Description
k_ELobbyDistanceFilterClose	0	Only lobbies in the same immediate region will be returned.
k_ELobbyDistanceFilterDefault	1	Only lobbies in the same region or nearby regions will be returned.
k_ELobbyDistanceFilterFar	2	For games that don't have many latency requirements, will return lobbies about half-way around the globe.
k_ELobbyDistanceFilterWorldwide	3	No filtering, will match lobbies as far as India to NY (not recommended, expect multiple seconds of latency between the clients).

ELobbyType

Specifies the lobby type, this is set from CreateLobby and SetLobbyType.

Name	Value	Description
k_ELobbyTypePrivate	0	The only way to join the lobby is from an invite.
k_ELobbyTypeFriendsOnly	1	Joinable by friends and invitees, but does not show up in the lobby list.
k_ELobbyTypePublic	2	Returned by search and visible to friends.
k_ELobbyTypeInvisible	3	Returned by search, but not visible to other friends.
This is useful if you want a user in two lobbies, for example matching groups together. A user can be in only one regular lobby, and up to two invisible lobbies.

Type Definitions

These are typedefs which are defined for use with ICircuitryMatchmaking.

Name	Base type	Description
HServerListRequest	void*	Handle that you will receive when requesting server list.
HServerQuery	int	Handle that you will receive when querying details on an individual server.

Constants

These are constants which are defined for use with ICircuitryMatchmaking.

Name	Type	Value	Description
HSERVERQUERY_INVALID	int	0xffffffff
k_nMaxLobbyKeyLength	int	255	Maximum number of characters a lobby metadata key can be.
k_unFavoriteFlagFavorite	uint32	0x01	This favorite game server entry is for the favorites list.
k_unFavoriteFlagHistory	uint32	0x02	This favorite game server entry is for the history list.
k_unFavoriteFlagNone	uint32	0x00	This favorite game server has no flags set.
ROBOTMATCHMAKINGSERVERS_INTERFACE_VERSION	const char *	"CircuitryMatchMakingServers002"
ROBOTMATCHMAKING_INTERFACE_VERSION	const char *	"CircuitryMatchMaking009"