gpg::TurnBasedMultiplayerManager

#include <turn_based_multiplayer_manager.h>

Fetches, modifies and creates TurnBasedMatch objects.

Summary

Public types

MatchInboxUICallback typedef
std::function< void(const MatchInboxUIResponse &)>
Defines a callback that can receive a MatchInboxUIResponse from ShowMatchInboxUI.
MultiplayerStatusCallback typedef
std::function< void(MultiplayerStatus)>
Defines a callback which can be used to receive a MultiplayerStatus.
PlayerSelectUICallback typedef
std::function< void(const PlayerSelectUIResponse &)>
Defines a callback that can receive a PlayerSelectUIResponse from ShowPlayerSelectUI.
TurnBasedMatchCallback typedef
std::function< void(const TurnBasedMatchResponse &)>
Defines a callback that can be used to receive a TurnBasedMatchResponse from one of the turn-based multiplayer operations.
TurnBasedMatchesCallback typedef
std::function< void(const TurnBasedMatchesResponse &)>
Defines a callback that can receive a TurnBasedMatchesResponse from one of the turn-based multiplayer operations.

Public static attributes

kAutomatchingParticipant
A participant which can be passed to methods which take a "next participant".

Public functions

AcceptInvitation(const MultiplayerInvitation & invitation, TurnBasedMatchCallback callback)
void
Asynchronously accepts a MultiplayerInvitation, and returns the result via a TurnBasedMatchCallback.
AcceptInvitationBlocking(Timeout timeout, const MultiplayerInvitation & invitation)
Blocking version of AcceptInvitation.
AcceptInvitationBlocking(const MultiplayerInvitation & invitation)
Overload of AcceptInvitationBlocking, which uses a default timeout of 10 years.
CancelMatch(const TurnBasedMatch & match, MultiplayerStatusCallback callback)
void
Asynchronously cancels a match.
CancelMatchBlocking(Timeout timeout, const TurnBasedMatch & match)
Blocking version of CancelMatch.
CancelMatchBlocking(const TurnBasedMatch & match)
Overload of CancelMatch which uses a default timeout of 10 years.
ConfirmPendingCompletion(const TurnBasedMatch & match, TurnBasedMatchCallback callback)
void
Confirms the results of a match that has ended and is pending local completion.
ConfirmPendingCompletionBlocking(Timeout timeout, const TurnBasedMatch & match)
Blocking version of ConfirmPendingCompletion.
ConfirmPendingCompletionBlocking(const TurnBasedMatch & match)
Overload of ConfirmPendingCompletionBlocking, which uses a default timeout of 10 years.
CreateTurnBasedMatch(const gpg::TurnBasedMatchConfig & config, TurnBasedMatchCallback callback)
void
Asynchronously creates a TurnBasedMatch using the provided TurnBasedMatchConfig.
CreateTurnBasedMatchBlocking(Timeout timeout, const gpg::TurnBasedMatchConfig & config)
Blocking version of CreateTurnBasedMatch.
CreateTurnBasedMatchBlocking(const gpg::TurnBasedMatchConfig & config)
Overload of CreateTurnBasedMatchBlocking, which uses a default timeout of 10 years.
DeclineInvitation(const MultiplayerInvitation & invitation)
void
DismissInvitation(const MultiplayerInvitation & invitation)
void
DismissMatch(const TurnBasedMatch & match)
void
Dismisses a TurnBasedMatch.
FetchMatch(const std::string & match_id, TurnBasedMatchCallback callback)
void
Asynchronously fetches a specific match by id.
FetchMatchBlocking(Timeout timeout, const std::string & match_id)
Blocking version of FetchMatch.
FetchMatchBlocking(const std::string & match_id)
Overload of FetchMatchBlocking, which uses a default timeout of 10 years.
FetchMatches(TurnBasedMatchesCallback callback)
void
Asynchronously fetches TurnBasedMatch and Invitation objects for the current player.
FetchMatchesBlocking(Timeout timeout)
Blocking version of FetchMatches.
FetchMatchesBlocking()
Overload of FetchMatchesBlocking, which uses a default timeout of 10 years.
FinishMatchDuringMyTurn(const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results, TurnBasedMatchCallback callback)
void
Asynchronously finishes the specified match.
FinishMatchDuringMyTurnBlocking(Timeout timeout, const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results)
Blocking version of FinishMatchDuringMyTurn.
FinishMatchDuringMyTurnBlocking(const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results)
Overload of FinishMatchDuringMyTurnBlocking, which uses a default timeout of 10 years.
LeaveMatchDuringMyTurn(const TurnBasedMatch & match, const MultiplayerParticipant & next_participant, MultiplayerStatusCallback callback)
void
Asynchronously leaves a match during the local participant's turn.
LeaveMatchDuringMyTurnBlocking(Timeout timeout, const TurnBasedMatch & match, const MultiplayerParticipant & next_participant)
Blocking version of LeaveMatchDuringMyTurn.
LeaveMatchDuringMyTurnBlocking(const TurnBasedMatch & match, const MultiplayerParticipant & next_participant)
Overload of LeaveMatchDuringMyTurnBlocking, which uses a default timeout of 10 years.
LeaveMatchDuringTheirTurn(const TurnBasedMatch & match, MultiplayerStatusCallback callback)
void
Asynchronously leaves a match during another participant's turn.
LeaveMatchDuringTheirTurnBlocking(Timeout timeout, const TurnBasedMatch & match)
Blocking version of LeaveMatchDuringTheirTurn.
LeaveMatchDuringTheirTurnBlocking(const TurnBasedMatch & match)
Overload of LeaveMatchDuringTheirTurnBlocking, which uses a default timeout of 10 years.
Rematch(const TurnBasedMatch & match, TurnBasedMatchCallback callback)
void
Rematches a match whose state is MatchStatus::COMPLETED.
RematchBlocking(Timeout timeout, const TurnBasedMatch & match)
Blocking version of Rematch.
RematchBlocking(const TurnBasedMatch & match)
Overload of RematchBlocking, which uses a default timeout of 10 years.
ShowMatchInboxUI(MatchInboxUICallback callback)
void
Asynchronously shows the match inbox UI, allowing the player to select a match or invitation.
ShowMatchInboxUIBlocking(Timeout timeout)
Blocking version of ShowMatchInboxUI.
ShowMatchInboxUIBlocking()
Overload of ShowMatchInboxUIBlocking, which uses a default timeout of 10 years.
ShowPlayerSelectUI(uint32_t minimum_players, uint32_t maximum_players, bool allow_automatch, PlayerSelectUICallback callback)
void
Asynchronously shows the player select UI, allowing the player to select other players to play a match with.
ShowPlayerSelectUIBlocking(Timeout timeout, uint32_t minimum_players, uint32_t maximum_players, bool allow_automatch)
Blocking version of ShowPlayerSelectUI.
ShowPlayerSelectUIBlocking(uint32_t minimum_players, uint32_t maximum_players, bool allow_automatch)
Overload of ShowPlayerSelectUIBlocking, which uses a default timeout of 10 years.
SynchronizeData()
void
Forces a sync of TBMP match data with the server.
TakeMyTurn(const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results, const MultiplayerParticipant & next_participant, TurnBasedMatchCallback callback)
void
Asynchronously takes the local participant's turn.
TakeMyTurnBlocking(Timeout timeout, const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results, const MultiplayerParticipant & next_participant)
Blocking version of TakeMyTurn.
TakeMyTurnBlocking(const TurnBasedMatch & match, std::vector< uint8_t > match_data, const ParticipantResults & results, const MultiplayerParticipant & next_participant)
Overload of TakeMyTurnBlocking, which uses a default timeout of 10 years.

Structs

gpg::TurnBasedMultiplayerManager::MatchInboxUIResponse

Data and ResponseStatus for the ShowMatchInboxUI operation.

gpg::TurnBasedMultiplayerManager::PlayerSelectUIResponse

Data and ResponseStatus for the ShowPlayerSelectUI operation.

gpg::TurnBasedMultiplayerManager::TurnBasedMatchResponse

Data and ResponseStatus for a specific TurnBasedMatch.

gpg::TurnBasedMultiplayerManager::TurnBasedMatchesResponse

Data and ResponseStatus for TurnBasedMatches and invitations.

Public types

MatchInboxUICallback

std::function< void(const MatchInboxUIResponse &)> MatchInboxUICallback

Defines a callback that can receive a MatchInboxUIResponse from ShowMatchInboxUI.

MultiplayerStatusCallback

std::function< void(MultiplayerStatus)> MultiplayerStatusCallback

Defines a callback which can be used to receive a MultiplayerStatus.

Used by the LeaveMatch and CancelMatch functions.

PlayerSelectUICallback

std::function< void(const PlayerSelectUIResponse &)> PlayerSelectUICallback

Defines a callback that can receive a PlayerSelectUIResponse from ShowPlayerSelectUI.

TurnBasedMatchCallback

std::function< void(const TurnBasedMatchResponse &)> TurnBasedMatchCallback

Defines a callback that can be used to receive a TurnBasedMatchResponse from one of the turn-based multiplayer operations.

TurnBasedMatchesCallback

std::function< void(const TurnBasedMatchesResponse &)> TurnBasedMatchesCallback

Defines a callback that can receive a TurnBasedMatchesResponse from one of the turn-based multiplayer operations.

Public static attributes

kAutomatchingParticipant

const MultiplayerParticipant kAutomatchingParticipant

A participant which can be passed to methods which take a "next participant".

This causes the method to select the next participant via automatching. It is only valid to pass kAutomatchingParticipant to a function if TurnBasedMatch::AutomatchingSlotsAvailable is more than 0 for the related match.

Public functions

AcceptInvitation

void AcceptInvitation(
  const MultiplayerInvitation & invitation,
  TurnBasedMatchCallback callback
)

Asynchronously accepts a MultiplayerInvitation, and returns the result via a TurnBasedMatchCallback.

If the operation is successful, the TurnBasedMatch returned via the callback is in the TurnBasedMatchState::MY_TURN state.

AcceptInvitationBlocking

TurnBasedMatchResponse AcceptInvitationBlocking(
  Timeout timeout,
  const MultiplayerInvitation & invitation
)

Blocking version of AcceptInvitation.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

AcceptInvitationBlocking

TurnBasedMatchResponse AcceptInvitationBlocking(
  const MultiplayerInvitation & invitation
)

Overload of AcceptInvitationBlocking, which uses a default timeout of 10 years.

CancelMatch

void CancelMatch(
  const TurnBasedMatch & match,
  MultiplayerStatusCallback callback
)

Asynchronously cancels a match.

The status returned via the MultiplayerStatusCallback indicates whether the operation succeeded. Match status must INVITED, THEIR_TURN, or MY_TURN for this function to be usable.

CancelMatchBlocking

MultiplayerStatus CancelMatchBlocking(
  Timeout timeout,
  const TurnBasedMatch & match
)

Blocking version of CancelMatch.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

CancelMatchBlocking

MultiplayerStatus CancelMatchBlocking(
  const TurnBasedMatch & match
)

Overload of CancelMatch which uses a default timeout of 10 years.

ConfirmPendingCompletion

void ConfirmPendingCompletion(
  const TurnBasedMatch & match,
  TurnBasedMatchCallback callback
)

Confirms the results of a match that has ended and is pending local completion.

This function can only be called when TurnBasedMatch::Status() returns MatchStatus::PENDING_COMPLETION.

Details
Parameters
match
The match whose completion to confirm.
callback
The callback receiving a TurnBasedMatchResponse.

ConfirmPendingCompletionBlocking

TurnBasedMatchResponse ConfirmPendingCompletionBlocking(
  Timeout timeout,
  const TurnBasedMatch & match
)

Blocking version of ConfirmPendingCompletion.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

ConfirmPendingCompletionBlocking

TurnBasedMatchResponse ConfirmPendingCompletionBlocking(
  const TurnBasedMatch & match
)

Overload of ConfirmPendingCompletionBlocking, which uses a default timeout of 10 years.

CreateTurnBasedMatch

void CreateTurnBasedMatch(
  const gpg::TurnBasedMatchConfig & config,
  TurnBasedMatchCallback callback
)

Asynchronously creates a TurnBasedMatch using the provided TurnBasedMatchConfig.

If creation is successful, this function returns the TurnBasedMatch via the provided TurnBasedMatchCallback. A newly created TurnBasedMatch always starts in the TurnBasedMatchState::MY_TURN state.

CreateTurnBasedMatchBlocking

TurnBasedMatchResponse CreateTurnBasedMatchBlocking(
  Timeout timeout,
  const gpg::TurnBasedMatchConfig & config
)

Blocking version of CreateTurnBasedMatch.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

CreateTurnBasedMatchBlocking

TurnBasedMatchResponse CreateTurnBasedMatchBlocking(
  const gpg::TurnBasedMatchConfig & config
)

Overload of CreateTurnBasedMatchBlocking, which uses a default timeout of 10 years.

DeclineInvitation

void DeclineInvitation(
  const MultiplayerInvitation & invitation
)

Declines a MultiplayerInvitation to a TurnBasedMatch.

Doing so cancels the match for the other participants, and removes the match from the local player's device.

DismissInvitation

void DismissInvitation(
  const MultiplayerInvitation & invitation
)

Dismisses a MultiplayerInvitation to a TurnBasedMatch.

This does not change the visible state of the TurnBasedMatch for the other participants, but removes the TurnBasedMatch from the local player's device.

DismissMatch

void DismissMatch(
  const TurnBasedMatch & match
)

Dismisses a TurnBasedMatch.

This does not change the visible state of the TurnBasedMatch for the other participants, but removes the TurnBasedMatch from the local player's device.

FetchMatch

void FetchMatch(
  const std::string & match_id,
  TurnBasedMatchCallback callback
)

Asynchronously fetches a specific match by id.

The result of this operation is returned via a TurnBasedMatchCallback.

FetchMatchBlocking

TurnBasedMatchResponse FetchMatchBlocking(
  Timeout timeout,
  const std::string & match_id
)

Blocking version of FetchMatch.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

FetchMatchBlocking

TurnBasedMatchResponse FetchMatchBlocking(
  const std::string & match_id
)

Overload of FetchMatchBlocking, which uses a default timeout of 10 years.

FetchMatches

void FetchMatches(
  TurnBasedMatchesCallback callback
)

Asynchronously fetches TurnBasedMatch and Invitation objects for the current player.

All active matches and up to 10 completed matches are returned.

FetchMatchesBlocking

TurnBasedMatchesResponse FetchMatchesBlocking(
  Timeout timeout
)

Blocking version of FetchMatches.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

FetchMatchesBlocking

TurnBasedMatchesResponse FetchMatchesBlocking()

Overload of FetchMatchesBlocking, which uses a default timeout of 10 years.

FinishMatchDuringMyTurn

void FinishMatchDuringMyTurn(
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results,
  TurnBasedMatchCallback callback
)

Asynchronously finishes the specified match.

This can be used rather than TakeMyTurn during the final turn of the match. Allows the caller to specify a final value for match_data, as well as a set of final values for ParticipantResults. After this operation is completed, the updated match is returned via the provided TurnBasedMatchCallback. This function can only be called when TurnBasedMatch::Status() returns MatchStatus::MY_TURN.

Details
Parameters
match
The match to finish.
match_data
A blob of data representing the final state of the match.
results
Any results for each player in the match. Note that these results must not contradict any results specified earlier via TakeTurn. Attempting to set different results for a player results in ERROR_INVALID_RESULTS.
callback
The callback that receives the TurnBasedMatchResponse.

FinishMatchDuringMyTurnBlocking

TurnBasedMatchResponse FinishMatchDuringMyTurnBlocking(
  Timeout timeout,
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results
)

Blocking version of FinishMatchDuringMyTurn.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

FinishMatchDuringMyTurnBlocking

TurnBasedMatchResponse FinishMatchDuringMyTurnBlocking(
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results
)

Overload of FinishMatchDuringMyTurnBlocking, which uses a default timeout of 10 years.

LeaveMatchDuringMyTurn

void LeaveMatchDuringMyTurn(
  const TurnBasedMatch & match,
  const MultiplayerParticipant & next_participant,
  MultiplayerStatusCallback callback
)

Asynchronously leaves a match during the local participant's turn.

The response returned via the TurnBasedMatchCallback contains the state of the match after the local player has gone. If this departure leaves the match with fewer than two participants, the match is canceled. match.Status() must return MatchStatus::MY_TURN for this function to be usable.

Details
Parameters
match
The match to leave.
next_participant
The participant whose turn is next. TurnBasedMultiplayerManager::kAutomatchingParticipant may be used to specify that the next participant should be selected via auto-matching.
callback
The callback that receives the TurnBasedMatchResponse

LeaveMatchDuringMyTurnBlocking

MultiplayerStatus LeaveMatchDuringMyTurnBlocking(
  Timeout timeout,
  const TurnBasedMatch & match,
  const MultiplayerParticipant & next_participant
)

Blocking version of LeaveMatchDuringMyTurn.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

LeaveMatchDuringMyTurnBlocking

MultiplayerStatus LeaveMatchDuringMyTurnBlocking(
  const TurnBasedMatch & match,
  const MultiplayerParticipant & next_participant
)

Overload of LeaveMatchDuringMyTurnBlocking, which uses a default timeout of 10 years.

LeaveMatchDuringTheirTurn

void LeaveMatchDuringTheirTurn(
  const TurnBasedMatch & match,
  MultiplayerStatusCallback callback
)

Asynchronously leaves a match during another participant's turn.

The response returned via the MultiplayerStatusCallback contains whether the local participant left the match successfully. If this departure leaves the match with fewer than two participants, the match is canceled. match.Status() must return MatchStatus::THEIR_TURN for this function to be usable.

LeaveMatchDuringTheirTurnBlocking

MultiplayerStatus LeaveMatchDuringTheirTurnBlocking(
  Timeout timeout,
  const TurnBasedMatch & match
)

Blocking version of LeaveMatchDuringTheirTurn.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

LeaveMatchDuringTheirTurnBlocking

MultiplayerStatus LeaveMatchDuringTheirTurnBlocking(
  const TurnBasedMatch & match
)

Overload of LeaveMatchDuringTheirTurnBlocking, which uses a default timeout of 10 years.

Rematch

void Rematch(
  const TurnBasedMatch & match,
  TurnBasedMatchCallback callback
)

Rematches a match whose state is MatchStatus::COMPLETED.

If the rematch is possible, TurnBasedMatchCallback receives the new match.

Details
Parameters
match
The match to rematch.
callback
The callback that receives a TurnBasedMatchResponse.

RematchBlocking

TurnBasedMatchResponse RematchBlocking(
  Timeout timeout,
  const TurnBasedMatch & match
)

Blocking version of Rematch.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

RematchBlocking

TurnBasedMatchResponse RematchBlocking(
  const TurnBasedMatch & match
)

Overload of RematchBlocking, which uses a default timeout of 10 years.

ShowMatchInboxUI

void ShowMatchInboxUI(
  MatchInboxUICallback callback
)

Asynchronously shows the match inbox UI, allowing the player to select a match or invitation.

Upon completion, the selected match or invitation is returned via the MatchInboxUICallback.

ShowMatchInboxUIBlocking

MatchInboxUIResponse ShowMatchInboxUIBlocking(
  Timeout timeout
)

Blocking version of ShowMatchInboxUI.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

ShowMatchInboxUIBlocking

MatchInboxUIResponse ShowMatchInboxUIBlocking()

Overload of ShowMatchInboxUIBlocking, which uses a default timeout of 10 years.

ShowPlayerSelectUI

void ShowPlayerSelectUI(
  uint32_t minimum_players,
  uint32_t maximum_players,
  bool allow_automatch,
  PlayerSelectUICallback callback
)

Asynchronously shows the player select UI, allowing the player to select other players to play a match with.

Upon completion, the selected players will be returned via the PlayerSelectUICallback.

ShowPlayerSelectUIBlocking

PlayerSelectUIResponse ShowPlayerSelectUIBlocking(
  Timeout timeout,
  uint32_t minimum_players,
  uint32_t maximum_players,
  bool allow_automatch
)

Blocking version of ShowPlayerSelectUI.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

ShowPlayerSelectUIBlocking

PlayerSelectUIResponse ShowPlayerSelectUIBlocking(
  uint32_t minimum_players,
  uint32_t maximum_players,
  bool allow_automatch
)

Overload of ShowPlayerSelectUIBlocking, which uses a default timeout of 10 years.

SynchronizeData

void SynchronizeData()

Forces a sync of TBMP match data with the server.

Receipt of new data triggers an OnTurnBasedMatchEventCallback or an OnMultiplayerInvitationReceivedCallback.

TakeMyTurn

void TakeMyTurn(
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results,
  const MultiplayerParticipant & next_participant,
  TurnBasedMatchCallback callback
)

Asynchronously takes the local participant's turn.

When taking a turn, the participant may specify a new value for match_data, as well as a set of ParticipantResults. When the turn is over, the updated match is returned via the TurnBasedMatchCallback. This function may only be called when TurnBasedMatch::Status() is MatchStatus::MY_TURN.

Details
Parameters
match
The match where the turn takes place.
match_data
A blob of data to send to the next participant.
results
Any known results for the match at the current time. Note that the result for a given player may only be specified once. Attempting to set different results for a player results in ERROR_INVALID_RESULTS.
next_participant
The participant whose turn is next. TurnBasedMultiplayerManager::kAutomatchingParticipant may be used to specify that the next participant should be selected via auto-matching.
callback
The callback that receives the TurnBasedMatchResponse.

TakeMyTurnBlocking

TurnBasedMatchResponse TakeMyTurnBlocking(
  Timeout timeout,
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results,
  const MultiplayerParticipant & next_participant
)

Blocking version of TakeMyTurn.

Allows the caller to specify a timeout in ms. After the specified time elapses, the function returns ERROR_TIMEOUT.

TakeMyTurnBlocking

TurnBasedMatchResponse TakeMyTurnBlocking(
  const TurnBasedMatch & match,
  std::vector< uint8_t > match_data,
  const ParticipantResults & results,
  const MultiplayerParticipant & next_participant
)

Overload of TakeMyTurnBlocking, which uses a default timeout of 10 years.