CloudBuilder  2.8.4
Making social games is easy !
Public Member Functions | Static Public Member Functions | Friends | List of all members
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 (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void ListMatches (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void FetchMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void JoinMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void InvitePlayer (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void DismissInvitation (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void PostMove (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void DrawFromShoe (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void LeaveMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void FinishMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
 
void DeleteMatch (CResultHandler *aHandler, const CHJSON *aConfiguration)
 

Static Public Member Functions

static CMatchManagerInstance ()
 

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

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

Creates a match, available for joining by others players.

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
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.
}
void CloudBuilder::CMatchManager::DeleteMatch ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis a JSON object. The mandatory keys are:
  • "id" (string): the ID of the match to delete.
Returns
if noErr, the json passed to the handler may contain:
  • "done" (number): 1 if done properly.
void CloudBuilder::CMatchManager::DismissInvitation ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis a JSON object. Must contain:
  • "id" (string): the ID of the match from which to remove the invitation.
Returns
if noErr, the json passed to the handler may contain:
  • "match" (object): updated match object as described in CreateMatch with low information detail.
void CloudBuilder::CMatchManager::DrawFromShoe ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
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.
void CloudBuilder::CMatchManager::FetchMatch ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

Fetches the latest info about a match.

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis a JSON object. The mandatory keys are:
  • "id" (string): the ID of the match.
Returns
if noErr, the json passed to the handler may contain:
  • "match" (object): fetched match object as described in CreateMatch
void CloudBuilder::CMatchManager::FinishMatch ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
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.
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
aHandlermatch result handler, to be called when the operation is completed
aConfigurationconfiguration of the match, as described in CreateMatch
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
aMatchmatch object to be dismissed
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
aHandlermatch result handler, to be called when the operation is completed
aConfigurationis 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.
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
aHandlermatch result handler, to be called when the operation is completed
aConfigurationis 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.
void CloudBuilder::CMatchManager::InvitePlayer ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
Returns
if noErr, the json passed to the handler may contain:
  • "match" (object): updated match object as described in CreateMatch with low information detail.
void CloudBuilder::CMatchManager::JoinMatch ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
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.
void CloudBuilder::CMatchManager::LeaveMatch ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
Returns
if noErr, the json passed to the handler may contain:
  • "match" (object): updated match object as described in CreateMatch.
void CloudBuilder::CMatchManager::ListMatches ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

Lists the matches available to join.

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
Returns
if noErr, the json passed to the handler may contain:
  • "matches" (array of objects): match objects as described in CreateMatch
void CloudBuilder::CMatchManager::PostMove ( CResultHandler aHandler,
const CHJSON aConfiguration 
)

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

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aConfigurationis 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.
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: