gpg::SnapshotManager

#include <snapshot_manager.h>

Gets and sets various snapshot-related data.

Summary

If the app does not enable snapshots at authentication time (see GameServices::Builder::EnableSnapshots), most methods on SnapshotManager will fail.

Public types
CommitCallback typedef
std::function< void(const CommitResponse &)>
Defines a callback type that receives an CommitResponse.
FetchAllCallback typedef
std::function< void(const FetchAllResponse &)>
Defines a callback type that receives a FetchAllResponse.
MaxSizeCallback typedef
std::function< void(const MaxSizeResponse &)>
Defines a callback type that receives a MaxSizeResponse.
OpenCallback typedef
std::function< void(const OpenResponse &)>
Defines a callback type that receives an OpenResponse.
ReadCallback typedef
std::function< void(const ReadResponse &)>
Defines a callback type that receives a ReadResponse.
SnapshotSelectUICallback typedef
std::function< void(const SnapshotSelectUIResponse &)>
Defines a callback that can receive a SnapshotSelectUIResponse from ShowSelectUIOperation.

Public functions
Commit(const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > data, CommitCallback callback)
void
Asynchronously commits the data provided to the snapshot, and updates the metadata of the snapshot using the provided metadata object.
CommitBlocking(const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
Synchronously commits the data provided to the snapshot, and updates the metadata of the snapshot using the provided metadata object.
CommitBlocking(Timeout timeout, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
Synchronously commits the data provided to the snapshot and updates the metadata of the snapshot using the provided metadata object.
Delete(const SnapshotMetadata & snapshot_metadata)
void
Deletes the specified snapshot.
FetchAll(FetchAllCallback callback)
void
Asynchronously loads all snapshot data for the currently signed-in player.
FetchAll(DataSource data_source, FetchAllCallback callback)
void
Asynchronously loads all snapshot data for the currently signed-in player.
FetchAllBlocking()
Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.
FetchAllBlocking(DataSource data_source)
Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.
FetchAllBlocking(Timeout timeout)
Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.
FetchAllBlocking(DataSource data_source, Timeout timeout)
Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.
GetMaxSize(MaxSizeCallback callback) const
void
Asynchronously gets the maximum data size and the maximum cover image size per snapshot in bytes.
GetMaxSizeBlocking() const
Synchronously gets the maximum data size and the maximum cover image size per snapshot in bytes, directly returning the MaxSizeResponse.
GetMaxSizeBlocking(Timeout timeout) const
Synchronously gets the maximum data size and the maximum cover image size per snapshot in bytes, directly returning the MaxSizeResponse.
Open(const std::string & file_name, SnapshotConflictPolicy conflict_policy, OpenCallback callback)
void
Asynchronously opens a snapshot with the given name.
Open(DataSource data_source, const std::string & file_name, SnapshotConflictPolicy conflict_policy, OpenCallback callback)
void
Deprecated. data_source is ignored. Use Open(file_name, conflict_policy, callback) instead.
Asynchronously opens a snapshot with the given name.
OpenBlocking(const std::string & file_name, SnapshotConflictPolicy conflict_policy)
Synchronously opens a snapshot with the given name.
OpenBlocking(Timeout timeout, const std::string & file_name, SnapshotConflictPolicy conflict_policy)
Synchronously opens a snapshot with the given name.
OpenBlocking(DataSource data_source, const std::string & file_name, SnapshotConflictPolicy conflict_policy) Deprecated. data_source is ignored. Use OpenBlocking(file_name, conflict_policy) instead.
Synchronously opens a snapshot with the given name.
OpenBlocking(DataSource data_source, Timeout timeout, const std::string & file_name, SnapshotConflictPolicy conflict_policy) Deprecated. data_source is ignored. Use OpenBlocking(timeout, file_name, conflict_policy) instead.
Synchronously opens a snapshot with the given name.
Read(const SnapshotMetadata & snapshot_metadata, ReadCallback callback)
void
Asynchronously reads a snapshot off of the disk, and copies it into memory.
ReadBlocking(const SnapshotMetadata & snapshot_metadata)
Synchronously reads a snapshot off of the disk, and copies it into memory.
ReadBlocking(Timeout timeout, const SnapshotMetadata & snapshot_metadata)
Synchronously reads a snapshot off of the disk and copies it into memory.
ResolveConflict(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, OpenCallback callback)
void
Asynchronously resolves a conflict using the data from the provided snapshot.
ResolveConflict(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents, OpenCallback callback)
void
Asynchronously resolves a conflict using the provided data.
ResolveConflictBlocking(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata)
Synchronously resolves a conflict using the data from the provided snapshot.
ResolveConflictBlocking(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
Synchronously resolves a conflict using the provided data.
ResolveConflictBlocking(Timeout timeout, const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata)
Synchronously resolves a conflict using the data from the provided snapshot.
ResolveConflictBlocking(Timeout timeout, const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
Synchronously resolves a conflict using the provided data.
ShowSelectUIOperation(bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title, SnapshotSelectUICallback callback)
void
Asynchronously shows the snapshot UI, allowing the player to select a snapshot or request a new snapshot.
ShowSelectUIOperationBlocking(Timeout timeout, bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title)
Blocking version of ShowSelectUIOperation.
ShowSelectUIOperationBlocking(bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title)
Overload of ShowSelectUIOperationBlocking, which uses a default timeout of 10 years.

Structs
gpg::SnapshotManager::CommitResponse

Holds the data for an updated snapshot, along with a response status.

gpg::SnapshotManager::FetchAllResponse

Holds all data for all snapshots, along with a response status.

gpg::SnapshotManager::MaxSizeResponse

Holds max size for snapshot data and for snapshot cover image.

gpg::SnapshotManager::OpenResponse

Holds the data for a particular requested snapshot along with a response status.

gpg::SnapshotManager::ReadResponse

Reads response status and snapshot data returned from a snapshot read operation.

gpg::SnapshotManager::SnapshotSelectUIResponse

Data and ResponseStatus for the ShowSelectUIOperation operation.

Public types

CommitCallback

std::function< void(const CommitResponse &)> CommitCallback

Defines a callback type that receives an CommitResponse.

This callback type is provided to the Commit(*) and ResolveConflict(*) functions below.

FetchAllCallback

std::function< void(const FetchAllResponse &)> FetchAllCallback

Defines a callback type that receives a FetchAllResponse.

This callback type is provided to the FetchAll(*) functions below.

MaxSizeCallback

std::function< void(const MaxSizeResponse &)> MaxSizeCallback

Defines a callback type that receives a MaxSizeResponse.

This callback type is provided to the GetMaxSize.

OpenCallback

std::function< void(const OpenResponse &)> OpenCallback

Defines a callback type that receives an OpenResponse.

This callback type is provided to the Open(*) functions below.

ReadCallback

std::function< void(const ReadResponse &)> ReadCallback

Defines a callback type that receives a ReadResponse.

This callback type is provided to the Read(*) functions below.

SnapshotSelectUICallback

std::function< void(const SnapshotSelectUIResponse &)> SnapshotSelectUICallback

Defines a callback that can receive a SnapshotSelectUIResponse from ShowSelectUIOperation.

Public functions

Commit

void Commit(
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > data,
  CommitCallback callback
)

Asynchronously commits the data provided to the snapshot, and updates the metadata of the snapshot using the provided metadata object.

Calls the provided CommitCallback upon operation completion.

CommitBlocking

CommitResponse CommitBlocking(
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > contents
)

Synchronously commits the data provided to the snapshot, and updates the metadata of the snapshot using the provided metadata object.

CommitBlocking

CommitResponse CommitBlocking(
  Timeout timeout,
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > contents
)

Synchronously commits the data provided to the snapshot and updates the metadata of the snapshot using the provided metadata object.

Specify timeout in milliseconds.

Delete

void Delete(
  const SnapshotMetadata & snapshot_metadata
)

Deletes the specified snapshot.

This will delete the data of the snapshot locally and on the server.

FetchAll

void FetchAll(
  FetchAllCallback callback
)

Asynchronously loads all snapshot data for the currently signed-in player.

Calls the provided FetchAllCallback upon operation completion. Not specifying data_source makes this function call equivalent to calling FetchAll(DataSource data_source, FetchAllCallback callback), with data_source specified as CACHE_OR_NETWORK.

FetchAll

void FetchAll(
  DataSource data_source,
  FetchAllCallback callback
)

Asynchronously loads all snapshot data for the currently signed-in player.

Calls the provided FetchAllCallback upon operation completion. Specify data_source as CACHE_OR_NETWORK or NETWORK_ONLY.

FetchAllBlocking

FetchAllResponse FetchAllBlocking()

Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.

Specifying neither data_source nor timeout makes this function call equivalent to calling FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout), with data_source specified as CACHE_OR_NETWORK, and timeout specified as 10 years.

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  DataSource data_source
)

Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.

Specify data_source as CACHE_OR_NETWORK or NETWORK_ONLY. Not specifying timeout makes this function call equivalent to calling FetchAllBlocking FetchAllResponse(DataSource data_source, Timeout timeout), with your specified data_source value, and timeout specified as 10 years.

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  Timeout timeout
)

Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.

Specify timeout in milliseconds. Not specifying data_source makes this function call equivalent to calling FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout), with data_source specified as CACHE_OR_NETWORK, and timeout containing your specified value.

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  DataSource data_source,
  Timeout timeout
)

Synchronously loads all snapshot data for the currently signed-in player, directly returning the FetchAllResponse.

Specify data_source as CACHE_OR_NETWORK or NETWORK_ONLY. Specify timeout in milliseconds.

GetMaxSize

void GetMaxSize(
  MaxSizeCallback callback
) const

Asynchronously gets the maximum data size and the maximum cover image size per snapshot in bytes.

Calls the provided MaxSizeCallback upon operation completion.

The maximum data size per snapshot guaranteed to be at least 3 MB. May increase in the future.

The maximum data size per snapshot cover image guaranteed to be at least 800 KB. May increase in the future.

GetMaxSizeBlocking

MaxSizeResponse GetMaxSizeBlocking() const

Synchronously gets the maximum data size and the maximum cover image size per snapshot in bytes, directly returning the MaxSizeResponse.

The maximum data size per snapshot guaranteed to be at least 3 MB. May increase in the future.

The maximum data size per snapshot cover image guaranteed to be at least 800 KB. May increase in the future.

GetMaxSizeBlocking

MaxSizeResponse GetMaxSizeBlocking(
  Timeout timeout
) const

Synchronously gets the maximum data size and the maximum cover image size per snapshot in bytes, directly returning the MaxSizeResponse.

The maximum data size per snapshot guaranteed to be at least 3 MB. May increase in the future.

The maximum data size per snapshot cover image guaranteed to be at least 800 KB. May increase in the future.

Specify timeout in milliseconds.

Open

void Open(
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy,
  OpenCallback callback
)

Asynchronously opens a snapshot with the given name.

The specified snapshot will be created if it does not already exist. Calls the provided OpenCallback upon operation completion.

Snapshot names must be between 1 and 100 non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~").

Conflicts can occur if another device commits a snapshot between loading and committing a snapshot on the current device. You must resolve these conflicts. See OpenResponse above for more detail on conflicts.

conflict_policy can be one of the following values:

SnapshotConflictPolicy::MANUAL - In the event of a conflict, the response has state OpenResponse::VALID_WITH_CONFLICT. You must resolve the conflict using SnapshotManager::ResolveConflict. It is possible to see multiple conficts in a row, so check every time you call Open. This is the only policy where you will see the conflict. The rest handle resolution for you. This policy ensures that no user changes to the state of the save game will ever be lost.

SnapshotConflictPolicy::LONGEST_PLAYTIME - In the event of a conflict, the snapshot with the largest playtime value will be used. This policy is a good choice if the length of play time is a reasonable proxy for the "best" save game. Note that you must use SnapshotMetadataChange::Builder::SetPlayedTime() when saving games for this policy to be meaningful.

SnapshotConflictPolicy::LAST_KNOWN_GOOD - In the event of a conflict, the base snapshot will be used. This policy is a reasonable choice if your game requires stability from the snapshot data. This policy ensures that only writes which are not contested are seen by the player, which guarantees that all clients converge. Note: previously SnapshotManager::BASE_WINS

SnapshotConflictPolicy::MOST_RECENTLY_MODIFIED - In the event of a conflict, the remote will be used. This policy is a reasonable choice if your game can tolerate players on multiple devices clobbering their own changes. Because this policy blindly chooses the most recent data, it is possible that a player's changes may get lost. Note: previously SnapshotManager::REMOTE_WINS

SnapshotConflictPolicy::HIGHEST_PROGRESSIn the case of a conflict, the snapshot with the highest progress value will be used. In the case of a tie, the last known good snapshot will be chosen instead. This policy is a good choice if your game uses the progress value of the snapshot to determine the best saved game. Note that you must use SnapshotMetadataChange::Builder::SetPlayedTime() when saving games for this policy to be meaningful.

Open

void Open(
  DataSource data_source,
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy,
  OpenCallback callback
)

Asynchronously opens a snapshot with the given name.

Deprecated. data_source is ignored. Use Open(file_name, conflict_policy, callback) instead.

OpenBlocking

OpenResponse OpenBlocking(
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy
)

Synchronously opens a snapshot with the given name.

The specified snapshot will be created if it does not already exist.

See Open for more details.

OpenBlocking

OpenResponse OpenBlocking(
  Timeout timeout,
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy
)

Synchronously opens a snapshot with the given name.

The specified snapshot will be created if it does not already exist.

Specify timeout in milliseconds.

See Open for more details.

OpenBlocking

OpenResponse OpenBlocking(
  DataSource data_source,
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy
)

Synchronously opens a snapshot with the given name.

Deprecated. data_source is ignored. Use OpenBlocking(file_name, conflict_policy) instead.

OpenBlocking

OpenResponse OpenBlocking(
  DataSource data_source,
  Timeout timeout,
  const std::string & file_name,
  SnapshotConflictPolicy conflict_policy
)

Synchronously opens a snapshot with the given name.

Deprecated. data_source is ignored. Use OpenBlocking(timeout, file_name, conflict_policy) instead.

Read

void Read(
  const SnapshotMetadata & snapshot_metadata,
  ReadCallback callback
)

Asynchronously reads a snapshot off of the disk, and copies it into memory.

The data is passed back by value for easier modification. Each call to this function results in a full read. This means that it is typically best only to read a snapshot once. Calls the provided ReadCallback upon operation completion.

ReadBlocking

ReadResponse ReadBlocking(
  const SnapshotMetadata & snapshot_metadata
)

Synchronously reads a snapshot off of the disk, and copies it into memory.

The data is passed back by value for easier modification. Each call to this function results in a full read. This means that it is typically best only to read a snapshot once. Not specifying timeout makes this function call equivalent to calling ReadBlocking ReadBlocking(Timeout timeout, const SnapshotMetadata& snapshot_metadata), with timeout specified as 10 years.

ReadBlocking

ReadResponse ReadBlocking(
  Timeout timeout,
  const SnapshotMetadata & snapshot_metadata
)

Synchronously reads a snapshot off of the disk and copies it into memory.

The data is passed back by value for easier modification. Each call to this does a full read so typically only read a snapshot once. Specify timeout in milliseconds.

ResolveConflict

void ResolveConflict(
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata,
  OpenCallback callback
)

Asynchronously resolves a conflict using the data from the provided snapshot.

This will replace the data on the server with the specified snapshot. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

Calls the provided OpenCallback upon operation completion.

ResolveConflict

void ResolveConflict(
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > contents,
  OpenCallback callback
)

Asynchronously resolves a conflict using the provided data.

This will replace the data on the server with the specified metadata changes and contents. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Values which are not included in the metadata change will be resolved to the version currently on the server.

Note that the total size of the contents may not exceed the maxDataSize provided by GetMaxSize.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

Calls the provided OpenCallback upon operation completion.

ResolveConflictBlocking

OpenResponse ResolveConflictBlocking(
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata
)

Synchronously resolves a conflict using the data from the provided snapshot.

This will replace the data on the server with the specified snapshot. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

ResolveConflictBlocking

OpenResponse ResolveConflictBlocking(
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > contents
)

Synchronously resolves a conflict using the provided data.

This will replace the data on the server with the specified metadata changes and contents. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Values which are not included in the metadata change will be resolved to the version currently on the server.

Note that the total size of the contents may not exceed the maxDataSize provided by GetMaxSize.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

ResolveConflictBlocking

OpenResponse ResolveConflictBlocking(
  Timeout timeout,
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata
)

Synchronously resolves a conflict using the data from the provided snapshot.

This will replace the data on the server with the specified snapshot. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

Specify timeout in milliseconds.

ResolveConflictBlocking

OpenResponse ResolveConflictBlocking(
  Timeout timeout,
  const std::string & conflict_id,
  const SnapshotMetadata & snapshot_metadata,
  const SnapshotMetadataChange & metadata_change,
  std::vector< uint8_t > contents
)

Synchronously resolves a conflict using the provided data.

This will replace the data on the server with the specified metadata changes and contents. Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

Values which are not included in the metadata change will be resolved to the version currently on the server.

Note that the total size of the contents may not exceed the maxDataSize provided by GetMaxSize.

Calling this method with a snapshot that has already been committed or that was not opened via Open will fail with BaseStatus::ERROR_INTERNAL status.

Specify timeout in milliseconds.

ShowSelectUIOperation

void ShowSelectUIOperation(
  bool allow_create,
  bool allow_delete,
  uint32_t max_snapshots,
  const std::string & title,
  SnapshotSelectUICallback callback
)

Asynchronously shows the snapshot UI, allowing the player to select a snapshot or request a new snapshot.

Upon completion, the selected snapshot or new snapshot request are returned via the SnapshotSelectUICallback.

ShowSelectUIOperationBlocking

SnapshotSelectUIResponse ShowSelectUIOperationBlocking(
  Timeout timeout,
  bool allow_create,
  bool allow_delete,
  uint32_t max_snapshots,
  const std::string & title
)

Blocking version of ShowSelectUIOperation.

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

ShowSelectUIOperationBlocking

SnapshotSelectUIResponse ShowSelectUIOperationBlocking(
  bool allow_create,
  bool allow_delete,
  uint32_t max_snapshots,
  const std::string & title
)

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