CloudBuilder::CMatchManager Struct Reference

#include <CMatchManager.h>

Public Member Functions
void	Terminate ()
void	HLCreateMatch (CMatchResultHandler *aHandler, const CHJSON *aConfiguration)
void	HLJoinMatch (CMatchResultHandler *aHandler, const CHJSON *aConfiguration)
void	HLRestoreMatch (CMatchResultHandler *aHandler, const CHJSON *aConfiguration)
void	HLDestroyMatch (CMatch *aMatch)
void	CreateMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	ListMatches (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	FetchMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	JoinMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	InvitePlayer (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	DismissInvitation (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	PostMove (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	DrawFromShoe (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	LeaveMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	FinishMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
void	DeleteMatch (const CHJSON *aConfiguration, CResultHandler *aHandler)
DEPRECATED void	DeleteMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	FinishMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	LeaveMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	DrawFromShoe (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	PostMove (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	DismissInvitation (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	InvitePlayer (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	JoinMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	FetchMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	ListMatches (CResultHandler *aHandler, const CHJSON *aConfiguration)
DEPRECATED void	CreateMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)

Static Public Member Functions
static CMatchManager *	Instance ()

Friends
struct	singleton_holder< CMatchManager >

Detailed Description

The CMatchManager class is used to manage matches in a raw way. It also provides a higher level class which can be used to easily run a match at an higher level. Some methods accept a parameter named osn. This parameter can be used to forward a push notification to the users who are not active at the moment. It is typically a JSON with made of attributes which represent language -> message pairs. Here is an example: {"en": "Help me!", "fr": "Aidez moi!"}.

Member Function Documentation

CreateMatch()

void CloudBuilder::CMatchManager::CreateMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Creates a match, available for joining by others players.

Parameters

aConfiguration

is a JSON object holding the parameters of the match to create. It may contain the following: "domain" (string): the domain on which to create the match. "maxPlayers" (number): the maximum number of players who may be in the game at a time. "description" (optional string): string describing the match (available for other who want to join). "customProperties" (optional object of strings or numbers): freeform object containing the properties of the match, which may be used by other players to search for a suited match. "shoe" (optional array of objects): freeform object containing a list of objects which will be shuffled upon match creation. This offers an easy way to make a random generator that is safe, unbiased (since made on the server) and can be verified by all players once the game is finished.

aHandler

result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

"match": {
    "domain" (string): the domain to which the match belongs.
    "status" (string): the status of the game (running, finished).
    "description" (string): description of the match, defined by the user upon creation.
    "customProperties" (object of strings): custom properties, as passed.
    "events" (object of events): list of existing events, which may be used to reproduce the state of the game.
    "maxPlayers" (number): as passed.
    "players" (array of strings): the list of players IDs, should only contain you for now.
    "globalState" (object of strings): the global state of the game, which may be modified using a move.
    "lastEventId" (string or 0): the ID of the last event happened during this game; keep this for later.
    "match_id" (string): the ID of the created match. Keep this for later.
    "seed" (31-bit integer): a random seed that can be used to ensure consistent state across players of the game
    "shoe" (array of objects): an array of objects that are shuffled when the match starts. You can put anything
    you want inside and use it as values for your next game. This field is only returned when finishing a match.
} 

DeleteMatch()

void CloudBuilder::CMatchManager::DeleteMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Deletes a match. Only works if you are the one who created it and it is already finished.

Parameters

aConfiguration	is a JSON object. The mandatory keys are: "id" (string): the ID of the match to delete.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "done" (number): 1 if done properly.

DismissInvitation()

void CloudBuilder::CMatchManager::DismissInvitation	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Dismisses a pending invitation on a given match. Fails if the currently logged in player was not invited.

Parameters

aConfiguration	is a JSON object. Must contain: "id" (string): the ID of the match from which to remove the invitation.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch with low information detail.

DrawFromShoe()

void CloudBuilder::CMatchManager::DrawFromShoe	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Draws one or more randomized items from the shoe (see CreateMatch).

Parameters

aConfiguration	is a JSON object. The following attributes are mandatory: "id" (string): the ID of the match. "lastEventId" (string): the ID of the last event received for this match. And optionally: "count" (integer): the number of items to draw (defaults to 1). "osn" (object): please see the definition of the CMatchManager class for more information about this.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "drawnItems" (array of objects): the objects drawn as passed in the shoe element at CreateMatch.
• "match" (object): updated match object as described in CreateMatch. Please take note of the lastEventId for next requests.

FetchMatch()

void CloudBuilder::CMatchManager::FetchMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Fetches the latest info about a match.

Parameters

aConfiguration	is a JSON object. The mandatory keys are: "id" (string): the ID of the match.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): fetched match object as described in CreateMatch

FinishMatch()

void CloudBuilder::CMatchManager::FinishMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Finishes a match. Only works if you are the one who created it in the first place. Other players will be notified in the form of an event of type 'match.finish'.

Parameters

aConfiguration

is a JSON object. The mandatory keys are: "id" (string): the ID of the match to leave. "lastEventId" (string): the ID of the last event received for this match. You received it either as a response of an operation on a match (such as when joining, or a move done by you) or as an event later (in case pass the _id of the last event received). Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.

aHandler

result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch. This key is NOT present if the delete attribute was passed.

HLCreateMatch()

void CloudBuilder::CMatchManager::HLCreateMatch	(	CMatchResultHandler *	aHandler,
		const CHJSON *	aConfiguration
	)

High level method which creates a match and passes it to the result handler in the form of a CMatch. Memory management of #CMatch objects is described on the class itself.

Parameters

aHandler	match result handler, to be called when the operation is completed
aConfiguration	configuration of the match, as described in CMatchManager::CreateMatch

HLDestroyMatch()

void CloudBuilder::CMatchManager::HLDestroyMatch

(

CMatch *

aMatch

)

Destroys a match object (not actually deleting the match or anything, just freeing the resource associated with the match).

Parameters

aMatch

match object to be dismissed

HLJoinMatch()

void CloudBuilder::CMatchManager::HLJoinMatch	(	CMatchResultHandler *	aHandler,
		const CHJSON *	aConfiguration
	)

High level method to join a match, resulting in a CMatch object allowing for easy manipulation on the match.

Parameters

aHandler	match result handler, to be called when the operation is completed
aConfiguration	is a JSON object. The mandatory keys are: "id" (string): the ID of the match to join. Needs to be either extracted from an invitation or simply by listing matches (see also ListMatches). Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.

HLRestoreMatch()

void CloudBuilder::CMatchManager::HLRestoreMatch	(	CMatchResultHandler *	aHandler,
		const CHJSON *	aConfiguration
	)

High level method to fetch a CMatch object corresponding to a match which the player already belongs to. It basically allows to continue the game in the same state as when the match has initially been created or joined to, all in a transparent manner.

Parameters

aHandler	match result handler, to be called when the operation is completed
aConfiguration	is a JSON object. It may contain the following keys: "id" (string): ID of the match to resume. If may not be passed, in which case the last match from the given domain to which the user is participating will be used. "domain" (string): the domain on which the match to be resumed belongs; not used if id is passed and defaulted to private if not passed.

InvitePlayer()

void CloudBuilder::CMatchManager::InvitePlayer	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Allows to invite a player to join a match. You need to be part of the match to send an invitation. This can be used for private matches as described in the chapter Working with matches.

Parameters

aConfiguration	is a JSON object. The manadatory keys are: "id" (string): the ID of the match to invite the player to. "gamer_id" (string): the ID of the player to invite. Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch with low information detail.

JoinMatch()

void CloudBuilder::CMatchManager::JoinMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Joins a match. Other players will be notified in the form of an event of type 'match.join'.

Parameters

aConfiguration	is a JSON object. The mandatory keys are: "id" (string): the ID of the match to join. Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch. Please take note of the lastEventId contained.

LeaveMatch()

void CloudBuilder::CMatchManager::LeaveMatch	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Leaves a match. Only works if you have joined it prior to calling this. Other players will be notified in the form of an event of type 'match.leave'.

Parameters

aConfiguration	is a JSON object. The mandatory keys are: "id" (string): the ID of the match to leave. Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.
aHandler	result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch.

ListMatches()

void CloudBuilder::CMatchManager::ListMatches	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Lists the matches available to join.

Parameters

aConfiguration

is a JSON object allowing to filter the matches to be returned. You may pass any of these: "domain" (string): the domain on which to look for available matches. "filter" (object of string): a list of properties that need to match inside the customProperties field of a match. Do NOT pass "participating" if you pass this attribute. "participating" (anything): pass this attribute along with any value (but NO filter in that case) to list all matches to which you are participating. "invited" (anything): filter out by matches you are invited to. "finished" (anything): also include finished games. "full" (anything): pass this attribute to also include games where the maximum number of player has been reached. "limit" (number): the maximum number of results to return. For pagination, defaulting to 30. "skip" (number): the first element to start from. Use skip=30&limit=30 to fetch the second page.

aHandler

result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "matches" (array of objects): match objects as described in CreateMatch

PostMove()

void CloudBuilder::CMatchManager::PostMove	(	const CHJSON *	aConfiguration,
		CResultHandler *	aHandler
	)

Posts a move in the match, notifying other players in the form of an event of type 'match.move'.

Parameters

aConfiguration

is a JSON object. It may contain the following: "id" (string): the ID of the match in which to post the move. "move" (object of strings or numbers): freeform object describing the move made by the player; will be reported to other players and left pending in the queue of the match. May be used by newcomers to reproduce the same game state locally as a player who joined earlier (events would then be "replayed" locally). "globalState" (optional object of strings or numbers): freeform object describing the global state of the game. When passed, it indicates that there is a consistent game state that newcomers may use to start the game from. As such, the list of pending events in the match will be cleared (but people who are currently in the game will still receive all notifications triggered since they joined). Thus, you should consider passing a global state sometimes, it will ease the work for newcomers. "lastEventId" (string): the ID of the last event received for this match. Optionally, an osn node can be passed. Please see the definition of the CMatchManager class for more information about this.

aHandler

result handler whenever the call finishes (it might also be synchronous)

Returns

if noErr, the json passed to the handler may contain:

• "match" (object): updated match object as described in CreateMatch. Please take note of the lastEventId contained.

---

The documentation for this struct was generated from the following file:

• E:/XtraLife/GitHub/XtraLife/cloudbuilder/CloudBuilder/Headers/CMatchManager.h