GPGTurnBasedMatch Class Reference

GPGTurnBasedMatch Class Reference

Overview

The main object to represent a turn-based match.

This encapsulates all the data relating to how the match was created, who is playing, the current state, your games's match data (or game state), as well as results when the match is completed.

Public Member Functions

(BOOL) - canParticipantTakeTurn:
(NSString *) - participantIdForPlayerId:
(GPGTurnBasedParticipant *) - participantForId:
(GPGTurnBasedParticipantResult *) - resultForParticipantId:
(GPGTurnBasedParticipantStatus) - statusForPlayerId:
(void) - cancelWithCompletionHandler:
 Cancels a turn-based match from the match list.
(void) - declineWithCompletionHandler:
 Declines an invitation to play a turn-based match.
(void) - dismissWithCompletionHandler:
 Dismisses a turn-based match from the match list.
(void) - finishWithData:results:completionHandler:
 Finishes a turn-based match.
(void) - joinWithCompletionHandler:
 Joins a turn-based match that the player has been invited to.
(void) - leaveOutOfTurnWithCompletionHandler:
 Leaves a turn-based match when it is not the current player's turn, without canceling the match.
(void) - leaveDuringTurnWithNextParticipantId:completionHandler:
 Leave a turn-based match during the current player's turn, without canceling the match.
(void) - rematchWithCompletionHandler:
 Creates a rematch of a match that was previously completed, with the same participants.
(void) - takeTurnWithNextParticipantId:data:results:completionHandler:
 Commits the results of a player's turn.

Static Public Member Functions

(GPGTurnBasedMatchCreationResult) + createMatchWithConfig:completionHandler:
 Creates a turn-based match.
(void) + fetchMatchWithId:includeMatchData:completionHandler:
 Gets the data for a turn-based match with a specified match ID.
(void) + listForIncludeMatchData:maxCompletedMatches:maxResults:pageToken:completionHandler:
 Returns turn-based matches the player is or was involved in.
(void) + allMatchesWithCompletionHandler:
 Returns all matches for the currently signed in player.
(void) + allMatchesFromDataSource:completionHandler:
 Returns all matches for the currently signed in player.
(void) + matchesForMatchStatus:completionHandler:
 Returns all matches for the currently signed in player that have a matching match status.
(void) + matchesForMatchStatus:dataSource:completionHandler:
 Returns all matches for the currently signed in player that have a matching match status.
(void) + matchesForUserMatchStatus:completionHandler:
 Returns all matches for the currently signed in player that have a matching user match status.
(void) + matchesForUserMatchStatus:dataSource:completionHandler:
 Returns all matches for the currently signed in player that have a matching user match status.

Properties

GPGMultiplayerConfigmatchConfig
 Criteria for auto-matching players into this match.
int64_t creationTimestamp
 Timestamp of the match creation.
GPGTurnBasedParticipantcreationParticipant
 The participant who created the match.
NSData * data
 The data / game state for this match.
BOOL dataAvailable
 True if this match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.
GPGTurnBasedParticipantinviterParticipant
 The participant that invited the user to the match.
int64_t lastUpdateTimestamp
 Timestamp of the last update to the match.
GPGTurnBasedParticipantlastUpdateParticipant
 The last participant to update the match.
NSString * matchDescription
 Localized short description for match based on turn state.
NSString * matchId
 Globally unique ID for a turn-based match.
int matchNumber
 The number of the match in a chain of rematches.
int matchVersion
 The version of this match: an increasing counter, used to avoid out-of-date updates to the match.
NSArray * participants
 The participants involved in the match, along with their statuses.
GPGTurnBasedParticipantpendingParticipant
 The participant that is taking a turn.
NSData * previousMatchData
 The data / game state for the previous match; set for the first turn of rematches only.
BOOL previousMatchDataAvailable
 True if the previous match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.
NSString * rematchId
 The ID of a rematch of this match.
NSArray * results
 The player results and placings reported for this match.
GPGTurnBasedMatchStatus status
 The status of the match.
GPGTurnBasedUserMatchStatus userMatchStatus
 The status of the current user in the match.
NSString * localParticipantId
GPGTurnBasedParticipantlocalParticipant
GPGPlayerpendingPlayer
BOOL myTurn
GPGTurnBasedParticipantResultmyResult
GPGTurnBasedParticipantStatus myStatus

Member Function Documentation

- (BOOL) canParticipantTakeTurn: (NSString *)  participantId
Parameters:
participantIdThe ID of the player to query.
Returns:
YES if the playerId corresponds to a player that can take a turn in this match.
- (NSString *) participantIdForPlayerId: (NSString *)  playerId
Returns:
The participant ID for this match that corresponds to the given player ID.
- (GPGTurnBasedParticipant *) participantForId: (NSString *)  participantId
Returns:
The GPGTurnBasedParticipant that corresponds to the participant ID.
- (GPGTurnBasedParticipantResult *) resultForParticipantId: (NSString *)  participantId
Returns:
The result for the requested participant.
Parameters:
participantIdThe ID for the player in the match for which to return results.
- (GPGTurnBasedParticipantStatus) statusForPlayerId: (NSString *)  playerId
Returns:
The current status of the player represented by playerId
Parameters:
playerIdThe ID of the player to query.
+ (GPGTurnBasedMatchCreationResult) createMatchWithConfig: (GPGMultiplayerConfig *)  config
completionHandler: (GPGTurnBasedMatchCreateBlock)  completionHandler 

Creates a turn-based match.

Parameters:
configThe GPGMultiplayerConfig instance that holds parameters for creating a match.
completionHandlerA block in the form: ^(GPGTurnBasedMatch *match, NSError *error)
+ (void) fetchMatchWithId: (NSString *)  matchId
includeMatchData: (BOOL)  includeMatchData
completionHandler: (GPGTurnBasedMatchGetBlock)  completionHandler 

Gets the data for a turn-based match with a specified match ID.

Parameters:
matchIdID of the match to fetch the data for.
includeMatchDataShould the data payload in the match be fetched as well.
completionHandlerA block in the form: ^(GPGTurnBasedMatch *match, NSError *error)
+ (void) listForIncludeMatchData: (BOOL)  includeMatchData
maxCompletedMatches: (int)  maxCompletedMatches
maxResults: (int)  maxResults
pageToken: (NSString *)  pageToken
completionHandler: (GPGTurnBasedMatchListBlock)  completionHandler 

Returns turn-based matches the player is or was involved in.

You can call this method to get match lists asynchronously.

Parameters:
includeMatchDataIndicate if the data payload in the matches should be fetched.
maxCompletedMatchesThe maximum count of completed matches to be returned.
maxResultsThe maximum count of total matches to be returned.
pageTokenThe pageToken given from the last call if pagination was needed. Set as nil for the start of the list or the entire list.
completionHandlerA block in the form: ^(NSArray *matches, NSString *pageToken, NSError *error)
+ (void) allMatchesWithCompletionHandler: (GPGTurnBasedMatchesBlock)  completionHandler

Returns all matches for the currently signed in player.

Parameters:
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
+ (void) allMatchesFromDataSource: (GPGDataSource)  dataSource
completionHandler: (GPGTurnBasedMatchesBlock)  completionHandler 

Returns all matches for the currently signed in player.

Parameters:
dataSourceThe data source from where to load.
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
+ (void) matchesForMatchStatus: (GPGTurnBasedMatchStatus)  status
completionHandler: (GPGTurnBasedMatchesBlock)  completionHandler 

Returns all matches for the currently signed in player that have a matching match status.

Parameters:
statusThe match status to filter matches on.
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
+ (void) matchesForMatchStatus: (GPGTurnBasedMatchStatus)  status
dataSource: (GPGDataSource)  dataSource
completionHandler: (GPGTurnBasedMatchesBlock)  completionHandler 

Returns all matches for the currently signed in player that have a matching match status.

Parameters:
statusThe match status to filter matches on.
dataSourceThe data source from where to load.
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
+ (void) matchesForUserMatchStatus: (GPGTurnBasedUserMatchStatus)  status
completionHandler: (GPGTurnBasedMatchesBlock)  completionHandler 

Returns all matches for the currently signed in player that have a matching user match status.

Parameters:
statusThe user match status to filter matches on.
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
+ (void) matchesForUserMatchStatus: (GPGTurnBasedUserMatchStatus)  status
dataSource: (GPGDataSource)  dataSource
completionHandler: (GPGTurnBasedMatchesBlock)  completionHandler 

Returns all matches for the currently signed in player that have a matching user match status.

Parameters:
statusThe user match status to filter matches on.
dataSourceThe data source from where to load.
completionHandlerA block in the form: ^(NSArray *matches, NSError *error)
- (void) cancelWithCompletionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler

Cancels a turn-based match from the match list.

You should only invoke this method on the user's turn in an active match. Once this call succeeds, the match will be removed from local storage. Note that this will cancel the match completely, forcing it to end for all players involved.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) declineWithCompletionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler

Declines an invitation to play a turn-based match.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) dismissWithCompletionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler

Dismisses a turn-based match from the match list.

The match will no longer show up in the list and will not generate notifications.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) finishWithData: (NSData *)  data
results: (NSArray *)  results
completionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler 

Finishes a turn-based match.

Each player should make this call once, after all results are in. Only the player whose turn it is may make the first call to Finish, and can pass in the final match state.

Parameters:
dataThe new data payload of the match.
resultsThe rank and status of the current players in the match given as GPGTurnBasedParticipantResult objects.
completionHandlerA block in the form: ^(NSError *error)
- (void) joinWithCompletionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler

Joins a turn-based match that the player has been invited to.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) leaveOutOfTurnWithCompletionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler

Leaves a turn-based match when it is not the current player's turn, without canceling the match.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) leaveDuringTurnWithNextParticipantId: (NSString *)  nextParticipantId
completionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler 

Leave a turn-based match during the current player's turn, without canceling the match.

Parameters:
completionHandlerA block in the form: ^(NSError *error)
- (void) rematchWithCompletionHandler: (GPGTurnBasedMatchRematchBlock)  completionHandler

Creates a rematch of a match that was previously completed, with the same participants.

This can be called by only one player on a match still in their list; the player must have called Finish first. The newly created match is paased to completionHandler.; it will be the caller's turn.

Parameters:
completionHandlerA block in the form: ^(GPGTurnBasedMatch *rematch, NSError *error)
- (void) takeTurnWithNextParticipantId: (NSString *)  nextParticipantId
data: (NSData *)  data
results: (NSArray *)  results
completionHandler: (GPGTurnBasedMatchCompletionBlock)  completionHandler 

Commits the results of a player's turn.

Parameters:
nextParticipantIdThe participant who should play next
dataThe new data payload of the match.
resultsThe rank and status of the current players in the match given as GPGTurnBasedParticipantResult objects.
completionHandlerA block in the form: ^(NSError *error)

Property Documentation

- (GPGMultiplayerConfig*) matchConfig [read, copy]

Criteria for auto-matching players into this match.

- (int64_t) creationTimestamp [read, assign]

Timestamp of the match creation.

The participant who created the match.

- (NSData*) data [read, copy]

The data / game state for this match.

- (BOOL) dataAvailable [read, assign]

True if this match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.

The participant that invited the user to the match.

Not set if the user was not invited to the match.

- (int64_t) lastUpdateTimestamp [read, assign]

Timestamp of the last update to the match.

The last participant to update the match.

- (NSString*) matchDescription [read, copy]

Localized short description for match based on turn state.

It is intended to be displayed when the match is shown in a list.

- (NSString*) matchId [read, copy]

Globally unique ID for a turn-based match.

- (int) matchNumber [read, assign]

The number of the match in a chain of rematches.

Will be set to 1 for the first match and incremented by 1 for each rematch.

- (int) matchVersion [read, assign]

The version of this match: an increasing counter, used to avoid out-of-date updates to the match.

- (NSArray*) participants [read, copy]

The participants involved in the match, along with their statuses.

Includes participants who have left or declined invitations. Type: GPGTurnBasedParticipant

The participant that is taking a turn.

We only store the IDs so the coredata model is simpler since they will already be persisted through the _participants field.

- (NSData*) previousMatchData [read, copy]

The data / game state for the previous match; set for the first turn of rematches only.

- (BOOL) previousMatchDataAvailable [read, assign]

True if the previous match has data available but it wasn't returned in a list response; fetching the match individually will retrieve this data.

- (NSString*) rematchId [read, copy]

The ID of a rematch of this match.

Only set for completed matches that have been rematched.

- (NSArray*) results [read, copy]

The player results and placings reported for this match.

Type: GPGTurnBasedParticipantResult

- (GPGTurnBasedMatchStatus) status [read, assign]

The status of the match.

- (GPGTurnBasedUserMatchStatus) userMatchStatus [read, assign]

The status of the current user in the match.

Derived from the match type, match status, the user's participant status, and the pending participant for this match.

- (NSString *) localParticipantId [read, copy]
Returns:
The participant ID for this match that corresponds to the logged-in player.
Returns:
The GPGTurnBasedParticipant that corresponds to the logged-in player.
- (GPGPlayer *) pendingPlayer [read, assign]
Returns:
The GPGPlayer who must take the next turn.
- (BOOL) myTurn [read, assign]
Returns:
YES if it is the currently logged-in player's turn.
Returns:
The result for the currently logged-in player.
- (GPGTurnBasedParticipantStatus) myStatus [read, assign]
Returns:
The current status of the currently logged-in player.