SnapshotsClient

public interfaceSnapshotsClient

A client to interact with Snapshots.

Nested Class Summary

class SnapshotsClient.DataOrConflict<T> Represents the result of attempting to open a snapshot or resolve a conflict from a previous attempt.
@interface SnapshotsClient.ResolutionPolicy Conflict resolution policy.
class SnapshotsClient.SnapshotConflict Result delivered when a conflict was detected during SnapshotsClient.open(SnapshotMetadata)or SnapshotsClient.resolveConflict(String, Snapshot).
class SnapshotsClient.SnapshotContentUnavailableApiException Indicates that the snapshot contents are unavailable at the moment, but the SnapshotMetadata is available through getSnapshotMetadata().

Constant Summary

int DISPLAY_LIMIT_NONE Constant passed to getSelectSnapshotIntent(String, boolean, boolean, int)indicating that the UI should not cap the number of displayed snapshots.
String EXTRA_SNAPSHOT_METADATA Intent extra used to pass aSnapshotMetadata.
String EXTRA_SNAPSHOT_NEW Intent extra used to indicate the user wants to create a new snapshot.
int RESOLUTION_POLICY_HIGHEST_PROGRESS In the case of a conflict, the snapshot with the highest progress value will be used.
int RESOLUTION_POLICY_LAST_KNOWN_GOOD In the case of a conflict, the last known good version of this snapshot will be used.
int RESOLUTION_POLICY_LONGEST_PLAYTIME In the case of a conflict, the snapshot with the longest played time will be used.
int RESOLUTION_POLICY_MANUAL In the case of a conflict, the result will be returned to the app for resolution.
int RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED In the case of a conflict, the most recently modified version of this snapshot will be used.

Public Method Summary

abstractTask<SnapshotMetadata>
commitAndClose(Snapshot snapshot, SnapshotMetadataChangemetadataChange)
Returns aTask which asynchronously commits any modifications in SnapshotMetadataChangemade to theSnapshot and loads a SnapshotMetadata.
abstractTask<String>
delete(SnapshotMetadata metadata)
Returns aTask which asynchronously deletes the specified by SnapshotMetadatasnapshot and loads the deleted snapshot ID.
abstractTask<Void>
discardAndClose(Snapshot snapshot)
Returns aTask which asynchronously discards the contents of theSnapshot and closes it.
abstractTask<Integer>
getMaxCoverImageSize()
Returns aTask which asynchronously loads the maximum data size per snapshot cover image in bytes.
abstractTask<Integer>
getMaxDataSize()
Returns aTask which asynchronously loads the maximum data size per snapshot in bytes.
abstractTask<Intent>
getSelectSnapshotIntent(Stringtitle, boolean allowAddButton, boolean allowDelete, int maxSnapshots)
Returns aTask which asynchronously loads anIntent that will let the user select a snapshot.
staticSnapshotMetadata
getSnapshotFromBundle(Bundleextras)
This method takes aBundle object and extracts theSnapshot provided.
abstractTask<AnnotatedData<SnapshotMetadataBuffer>>
load(boolean forceReload)
Returns aTask which asynchronously loads an annotated SnapshotMetadataBufferthat represents the snapshot data for the currently signed-in player.
abstractTask<DataOrConflict<Snapshot>>
open(SnapshotMetadata metadata)
Returns aTask which asynchronously opens a snapshot with the given SnapshotMetadata(usually returned from load(boolean).
abstractTask<DataOrConflict<Snapshot>>
open(SnapshotMetadata metadata, int conflictPolicy)
Returns aTask which asynchronously opens a snapshot with the given SnapshotMetadata(usually returned from load(boolean).
abstractTask<DataOrConflict<Snapshot>>
open(StringfileName, boolean createIfNotFound, int conflictPolicy)
Returns aTask which asynchronously opens a snapshot with the givenfileName.
abstractTask<DataOrConflict<Snapshot>>
open(StringfileName, boolean createIfNotFound)
Returns aTask which asynchronously opens a snapshot with the givenfileName.
abstractTask<DataOrConflict<Snapshot>>
resolveConflict(StringconflictId, String snapshotId, SnapshotMetadataChangemetadataChange,SnapshotContents snapshotContents)
Returns aTask which asynchronously resolves a conflict using the provided data.
abstractTask<DataOrConflict<Snapshot>>
resolveConflict(StringconflictId, Snapshot snapshot)
Returns aTask which asynchronously resolves a conflict using the data from the provided Snapshot.

Constants

public static final int DISPLAY_LIMIT_NONE

Constant passed to getSelectSnapshotIntent(String, boolean, boolean, int)indicating that the UI should not cap the number of displayed snapshots.

Constant Value:-1

public static finalString EXTRA_SNAPSHOT_METADATA

Intent extra used to pass aSnapshotMetadata.

See Intent.getParcelableExtra(String)

Constant Value: "com.google.android.gms.games.SNAPSHOT_METADATA"

public static finalString EXTRA_SNAPSHOT_NEW

Intent extra used to indicate the user wants to create a new snapshot.

See Intent.getBooleanExtra(String, boolean)

Constant Value: "com.google.android.gms.games.SNAPSHOT_NEW"

public static final int RESOLUTION_POLICY_HIGHEST_PROGRESS

In 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.setProgressValue(long)when saving games for this policy to be meaningful.

Constant Value:4

public static final int RESOLUTION_POLICY_LAST_KNOWN_GOOD

In the case of a conflict, the last known good version of this snapshot will be used. This corresponds to the data that would be returned from SnapshotsClient.SnapshotConflict.getSnapshot()in a custom merge.

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.

Constant Value:2

public static final int RESOLUTION_POLICY_LONGEST_PLAYTIME

In the case of a conflict, the snapshot with the longest played time 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 the length of play time is a reasonable proxy for the "best" save game. Note that you must use SnapshotMetadataChange.Builder.setPlayedTimeMillis(long)when saving games for this policy to be meaningful.

Constant Value:1

public static final int RESOLUTION_POLICY_MANUAL

In the case of a conflict, the result will be returned to the app for resolution. No automatic resolution will be performed.

This policy ensures that no user changes to the state of the save game will ever be lost.

Constant Value:-1

public static final int RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED

In the case of a conflict, the most recently modified version of this snapshot will be used. This corresponds to the data that would be returned from SnapshotsClient.SnapshotConflict.getConflictingSnapshot()in a custom merge.

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.

Constant Value:3

Public Methods

public abstractTask<SnapshotMetadata> commitAndClose(Snapshot snapshot,SnapshotMetadataChange metadataChange)

Returns aTaskwhich asynchronously commits any modifications inSnapshotMetadataChange made to theSnapshot and loads aSnapshotMetadata. TheTaskreturned by this method is complete once the changes are synced locally and the background sync request for this data has been requested.

This method fails aTaskwith an exception when called with a snapshot that was not opened or has already been committed/discarded.

Note that the total size of the contents ofsnapshotmay not exceed the size provided by getMaxDataSize().

Parameters
snapshot The snapshot to commit the data for.
metadataChange The set of changes to apply to the metadata for the snapshot. Use SnapshotMetadataChange.EMPTY_CHANGEto preserve the existing metadata.

public abstractTask<String> delete(SnapshotMetadata metadata)

Returns aTaskwhich asynchronously deletes the specified bySnapshotMetadata snapshot and loads the deleted snapshot ID. This will delete the data of the snapshot locally and on the server.

Parameters
metadata The metadata of the snapshot to delete.

public abstractTask<Void>discardAndClose(Snapshot snapshot)

Returns aTaskwhich asynchronously discards the contents of theSnapshot and closes it. This will discard all changes made to the file, and close the snapshot to future changes until it is re-opened. The file will not be modified on the server.

This method fails aTaskwith an exception when called with a snapshot that was not opened or has already been committed/discarded.

Parameters
snapshot The snapshot to discard the data for.

public abstractTask<Integer> getMaxCoverImageSize()

Returns aTaskwhich asynchronously loads the maximum data size per snapshot cover image in bytes. Guaranteed to be at least 800 KB. May increase in the future.

The returnedTaskcan fail with aRemoteException.

public abstractTask<Integer> getMaxDataSize()

Returns aTaskwhich asynchronously loads the maximum data size per snapshot in bytes. Guaranteed to be at least 3 MB. May increase in the future.

The returnedTaskcan fail with aRemoteException.

public abstractTask<Intent> getSelectSnapshotIntent(String title, boolean allowAddButton, boolean allowDelete, int maxSnapshots)

Returns aTaskwhich asynchronously loads anIntentthat will let the user select a snapshot. Note that theIntentreturned from theTaskmust be invoked with Activity.startActivityForResult(Intent, int),so that the identity of the calling package can be established.

The returnedTaskcan fail with aRemoteException.

If the user canceled without selecting a snapshot, the result will beActivity.RESULT_CANCELED. If the user selected a snapshot from the list, the result will beActivity.RESULT_OK and the data intent will contain the selected Snapshot as a parcelable object in EXTRA_SNAPSHOT_METADATA.If the user pressed the add button, the result will beActivity.RESULT_OK and the data intent will contain atrueboolean value in EXTRA_SNAPSHOT_NEW.

Note that if you have modified an open snapshot, the changes will not appear in this UI until you call commitAndClose(Snapshot, SnapshotMetadataChange)on the snapshot.

Parameters
title The title to display in the action bar of the returned Activity.
allowAddButton Whether or not to display a "create new snapshot" option in the selection UI.
allowDelete Whether or not to provide a delete overflow menu option for each snapshot in the selection UI.
maxSnapshots The maximum number of snapshots to display in the UI. Use DISPLAY_LIMIT_NONEto display all snapshots.

public staticSnapshotMetadata getSnapshotFromBundle(Bundle extras)

This method takes aBundleobject and extracts theSnapshot provided. If theBundleis invalid or does not contain the correct data, this method returns null.

Parameters
extras TheBundleto parse for aSnapshot object.
Returns

public abstractTask<AnnotatedData<SnapshotMetadataBuffer>> load(boolean forceReload)

Returns aTaskwhich asynchronously loads an annotatedSnapshotMetadataBuffer that represents the snapshot data for the currently signed-in player.

AbstractDataBuffer.release()should be called to release resources after usage.

Parameters
forceReload Iftrue,this call will clear any locally cached data and attempt to fetch the latest data from the server. This would commonly be used for something like a user-initiated refresh. Normally, this should be set tofalse to gain advantages of data caching.

public abstractTask<DataOrConflict<Snapshot>> open(SnapshotMetadata metadata)

Returns aTaskwhich asynchronously opens a snapshot with the givenSnapshotMetadata (usually returned fromload(boolean). To succeed, the snapshot must exist; i.e. this call will fail if the snapshot was deleted between the load and open calls.

This will open the snapshot using RESOLUTION_POLICY_MANUALas a conflict policy. If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved using resolveConflict(String, Snapshot)to continue with opening the snapshot.

If the snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
metadata The metadata of the existing snapshot to load.

public abstractTask<DataOrConflict<Snapshot>> open(SnapshotMetadata metadata, int conflictPolicy)

Returns aTaskwhich asynchronously opens a snapshot with the givenSnapshotMetadata (usually returned fromload(boolean). To succeed, the snapshot must exist; i.e. this call will fail if the snapshot was deleted between the load and open calls.

If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved using resolveConflict(String, Snapshot)to continue with opening the snapshot.

If the snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
metadata The metadata of the existing snapshot to load.
conflictPolicy The conflict resolution policy to use for this snapshot.

public abstractTask<DataOrConflict<Snapshot>> open(StringfileName, boolean createIfNotFound, int conflictPolicy)

Returns aTaskwhich asynchronously opens a snapshot with the givenfileName.If createIfNotFoundis set totrue,the specified snapshot will be created if it does not already exist.

If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved using resolveConflict(String, Snapshot)to continue with opening the snapshot.

If the snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
fileName The name of the snapshot file to open. Must be between 1 and 100 non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~" ).
createIfNotFound Iftrue,the snapshot will be created if one cannot be found.
conflictPolicy The conflict resolution policy to use for this snapshot.

public abstractTask<DataOrConflict<Snapshot>> open(StringfileName, boolean createIfNotFound)

Returns aTaskwhich asynchronously opens a snapshot with the givenfileName.If createIfNotFoundis set totrue,the specified snapshot will be created if it does not already exist.

This will open the snapshot using RESOLUTION_POLICY_MANUALas a conflict policy. If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved using resolveConflict(String, Snapshot)to continue with opening the snapshot.

If the snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
fileName The name of the snapshot file to open. Must be between 1 and 100 non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~" ).
createIfNotFound Iftrue,the snapshot will be created if one cannot be found.

public abstractTask<DataOrConflict<Snapshot>> resolveConflict(StringconflictId,StringsnapshotId,SnapshotMetadataChange metadataChange,SnapshotContents snapshotContents)

Returns aTaskwhich asynchronously resolves a conflict using the provided data. This will replace the data on the server with the specifiedSnapshotMetadataChange andSnapshotContents. 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.

If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved again using resolveConflict(String, Snapshot)to continue with opening the snapshot.

Note that the total size ofcontentsmay not exceed the size provided by getMaxDataSize().

Calling this method with a snapshot that has already been committed or that was not opened via open(SnapshotMetadata)will throw an exception.

If the resolved snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
conflictId The ID of the conflict to resolve. Must come from SnapshotsClient.SnapshotConflict.getConflictId().
snapshotId The ID of the snapshot to resolve the conflict for.
metadataChange The set of changes to apply to the metadata for the snapshot.
snapshotContents TheSnapshotContents to replace the snapshot data with.

public abstractTask<DataOrConflict<Snapshot>> resolveConflict(StringconflictId,Snapshot snapshot)

Returns aTaskwhich asynchronously resolves a conflict using the data from the providedSnapshot. This will replace the data on the server with the specifiedSnapshot.Note that it is possible for this operation to result in a conflict itself, in which case resolution should be repeated.

If a conflict occurred, the result's SnapshotsClient.DataOrConflict.isConflict()will returntrue, and the conflict will need to be resolved again using resolveConflict(String, Snapshot)to continue with opening the snapshot.

Note that the total size of the contents ofsnapshotmay not exceed the size provided by getMaxDataSize().

This method fails aTaskwith an exception when called with a snapshot that was not opened or has already been committed/discarded.

If the resolved snapshot's contents are unavailable, theTaskwill fail with SnapshotsClient.SnapshotContentUnavailableApiException.

Parameters
conflictId The ID of the conflict to resolve. Must come from SnapshotsClient.SnapshotConflict.getConflictId().
snapshot The snapshot to use to resolve the conflict.