CloudBuilder  2.8.4
Making social games is easy !
Public Types | Public Member Functions | List of all members
CloudBuilder::CMatch Struct Reference

#include <CMatchManager.h>

Inheritance diagram for CloudBuilder::CMatch:
CloudBuilder::CEventListener CotCHelpers::CRefClass

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 CHJSONGetPlayers ()
 
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)
 
CRefClassoperator= (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

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:

  • #CreateMatch (will result in a match that you are administrating)
  • #JoinMatch (will result in a normal match, except if you actually created it)
  • #FetchMatch (same as join, but works only for a match that you have actually joined/created first)
  • #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
    matchManagercurrent manager, used internally to prevent the use of this object after terminate
    resultresult received from a previous call as documented above

Member Function Documentation

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

Draws an item from the shoe.

Parameters
aHandlerresult handler whenever the call finishes (it might also be synchronous)
aCountthe number of items to draw from the shoe.
aOptionalAdditionalDataif 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 #CreateMatch.
  • "match" (object): updated match object as described in #CreateMatch.
void CloudBuilder::CMatch::Finish ( CMatchResultHandler *  aHandler,
bool  aDeleteToo,
const CHJSON aOptionalAdditionalData 
)

Requires to be the creator of the match.

Parameters
aHandlerthe result handler, which may be called synchronously
aDeleteTooif true, deletes the match if it finishes successfully or is already finished
aOptionalAdditionalDataif 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 #CreateMatch if the match hasn't been deleted.
  • "done" (number): set to 1 if the match has been successfully deleted as requested
const char* CloudBuilder::CMatch::GetGamerId ( )
Returns
the ID of the gamer (uses the UserManager for that purpose).
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
const char* CloudBuilder::CMatch::GetMatchId ( )
Returns
the match ID, may be useful to join a match later or invite friends.
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"));
}
State CloudBuilder::CMatch::GetStatus ( )
Returns
the current status of the match.
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).
void CloudBuilder::CMatch::Leave ( CMatchResultHandler *  aHandler,
const CHJSON aOptionalAdditionalData 
)

Leaves the match.

Parameters
aHandlerthe result handler, which may be called synchronously
aOptionalAdditionalDataif 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 #CreateMatch.
void CloudBuilder::CMatch::PostMove ( CMatchResultHandler *  aHandler,
const CHJSON aMoveData,
const CHJSON aOptionalUpdatedGameState,
const CHJSON aOptionalAdditionalData 
)

Posts a move to other players.

Parameters
aHandlerthe result handler, which may be called synchronously
aMoveDataa freeform JSON indicating your move so that others can track your progress
aOptionalUpdatedGameStatea freeform JSON replacing the global game state, to be used by players who join from now on
aOptionalAdditionalDataif 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 #CreateMatch.
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
aEventListenerthe 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.
void CloudBuilder::CMatch::UnregisterEventListener ( CMatchEventListener aEventListener)

Unregisters a previously registered event listener.

Parameters
aEventListenerevent 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: