CloudBuilder::CMatch Struct Reference

#include <CMatchManager.h>

Inheritance diagram for CloudBuilder::CMatch:

Public Types
enum	State { RUNNING = 1, FINISHED }

Public Member Functions
	CMatch (CMatchManager *matchManager, const CCloudResult *result)
const char *	GetGamerId ()
const char *	GetLastEventId ()
const char *	GetMatchId ()
const CHJSON *	GetPlayers ()
State	GetStatus ()
bool	IsCreator ()
void	RegisterEventListener (CMatchEventListener *aEventListener)
void	UnregisterEventListener (CMatchEventListener *aEventListener)
void	PostMove (CMatchResultHandler *aHandler, const CHJSON *aMoveData, const CHJSON *aOptionalUpdatedGameState, const CHJSON *aOptionalAdditionalData)
void	DrawFromShoe (CMatchResultHandler *aHandler, int aCount, const CHJSON *aOptionalAdditionalData)
void	Leave (CMatchResultHandler *aHandler, const CHJSON *aOptionalAdditionalData)
void	Finish (CMatchResultHandler *aHandler, bool aDeleteToo, const CHJSON *aOptionalAdditionalData)
Public Member Functions inherited from CotCHelpers::CRefClass
void	Retain ()
void	Release ()
	CRefClass (const CRefClass &other)
CRefClass &	operator= (const CRefClass &other)

Additional Inherited Members
Static Public Member Functions inherited from CotCHelpers::CRefClass
template<class T >
static T *	Retain (T *t)
template<class T >
static T *	Release (T *t)
Public Attributes inherited from CotCHelpers::CRefClass
unsigned	__ref_count

Detailed Description

Represents a match with which you can interact through high level functionality.

Memory management works as follows: in the CMatchResultHandler, you get a transient CRefClass object, which you have ownership on until you call CMatchManager::HLDestroyMatch. Thus, you may use autoref or call Retain/Release, but you shouldn't expect the CMatch to be usable beyond a corresponding call to CMatchManager::HLDestroyMatch.

Constructor & Destructor Documentation

CMatch()

CloudBuilder::CMatch::CMatch	(	CMatchManager *	matchManager,
		const CCloudResult *	result
	)

Constructs a high level match object allowing to use high level functions to control your match. You must call this with the result of one of the following calls:

• CMatchManager::CreateMatch (will result in a match that you are administrating)
• CMatchManager::JoinMatch (will result in a normal match, except if you actually created it)
• CMatchManager::FetchMatch (same as join, but works only for a match that you have actually joined/created first)
• CMatchManager::ListMatches, though you should avoid using it; it takes the last entry, so it works if you passed the participating parameter and are only participating to one match at a time. You should never call this constructor by yourself, but instead get your object as a result of a call like HLCreateMatch.

  Parameters

  matchManager	current manager, used internally to prevent the use of this object after terminate
  result	result received from a previous call as documented above

Member Function Documentation

DrawFromShoe()

void CloudBuilder::CMatch::DrawFromShoe	(	CMatchResultHandler *	aHandler,
		int	aCount,
		const CHJSON *	aOptionalAdditionalData
	)

Draws an item from the shoe.

Parameters

aHandler	result handler whenever the call finishes (it might also be synchronous)
aCount	the number of items to draw from the shoe.
aOptionalAdditionalData	if not null, can contain additional configuration. Currently supported nodes are 'osn'. 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 CMatchManager::CreateMatch.
• "match" (object): updated match object as described in CMatchManager::CreateMatch.

Finish()

void CloudBuilder::CMatch::Finish	(	CMatchResultHandler *	aHandler,
		bool	aDeleteToo,
		const CHJSON *	aOptionalAdditionalData
	)

Requires to be the creator of the match.

Parameters

aHandler	the result handler, which may be called synchronously
aDeleteToo	if true, deletes the match if it finishes successfully or is already finished
aOptionalAdditionalData	if not null, can contain additional configuration. Currently supported nodes are 'osn'. 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 CMatchManager::CreateMatch if the match hasn't been deleted.
• "done" (number): set to 1 if the match has been successfully deleted as requested

GetGamerId()

const char* CloudBuilder::CMatch::GetGamerId

(

)

Returns

the ID of the gamer (uses the UserManager for that purpose).

GetLastEventId()

const char* CloudBuilder::CMatch::GetLastEventId

(

)

This could be useful if you intend to use the raw API with an high level match, else forget it.

Returns

the ID of the last processed event

GetMatchId()

const char* CloudBuilder::CMatch::GetMatchId

(

)

Returns

the match ID, may be useful to join a match later or invite friends.

GetPlayers()

const CHJSON* CloudBuilder::CMatch::GetPlayers

(

)

Returns

the list of players as a JSON, that you can iterate like that:

for (const CHJSON *node: *match->GetPlayers()) {
   printf("Player ID: %s\n", node->GetString("gamer_id"));
} 

GetStatus()

State CloudBuilder::CMatch::GetStatus

(

)

Returns

the current status of the match.

IsCreator()

bool CloudBuilder::CMatch::IsCreator

(

)

Returns

whether you are the creator of the match, and as such have special privileges (like the ability to finish and delete a match).

Leave()

void CloudBuilder::CMatch::Leave	(	CMatchResultHandler *	aHandler,
		const CHJSON *	aOptionalAdditionalData
	)

Leaves the match.

Parameters

aHandler	the result handler, which may be called synchronously
aOptionalAdditionalData	if not null, can contain additional configuration. Currently supported nodes are 'osn'. 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 CMatchManager::CreateMatch.

PostMove()

void CloudBuilder::CMatch::PostMove	(	CMatchResultHandler *	aHandler,
		const CHJSON *	aMoveData,
		const CHJSON *	aOptionalUpdatedGameState,
		const CHJSON *	aOptionalAdditionalData
	)

Posts a move to other players.

Parameters

aHandler	the result handler, which may be called synchronously
aMoveData	a freeform JSON indicating your move so that others can track your progress
aOptionalUpdatedGameState	a freeform JSON replacing the global game state, to be used by players who join from now on
aOptionalAdditionalData	if not null, can contain additional configuration. Currently supported nodes are 'osn'. 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 CMatchManager::CreateMatch.

RegisterEventListener()

void CloudBuilder::CMatch::RegisterEventListener

(

CMatchEventListener *

aEventListener

)

Registers an event listener for this match. The benefit over the method in CMatchManager is that the events actually broadcasted are limited to those concerning this match.

Parameters

aEventListener

the listener to be called whenever an event comes for this match. It is a CRefClass, so if you don't need it, you can call Release(). The system will keep it as long as needed and free it then. As such, it is common to call Release() immediately after having registered an event listener. Never call delete on it.

UnregisterEventListener()

void CloudBuilder::CMatch::UnregisterEventListener

(

CMatchEventListener *

aEventListener

)

Unregisters a previously registered event listener.

Parameters

aEventListener

event listener to release (will free the memory if you released it on your side as well)

---

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

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