gpg::SnapshotManager

#include <snapshot_manager.h>

获取和设置各种快照相关数据。

摘要

如果应用在身份验证时未启用快照(请参阅 GameServices::Builder::EnableSnapshots),则 SnapshotManager 的大多数方法都将失败。

公共类型

CommitCallback typedef
std::function< void(const CommitResponse &)>
定义接收 CommitResponse 的回调类型。
FetchAllCallback typedef
std::function< void(const FetchAllResponse &)>
定义接收 FetchAllResponse 的回调类型。
MaxSizeCallback typedef
std::function< void(const MaxSizeResponse &)>
定义接收 MaxSizeResponse 的回调类型。
OpenCallback typedef
std::function< void(const OpenResponse &)>
定义接收 OpenResponse 的回调类型。
ReadCallback typedef
std::function< void(const ReadResponse &)>
定义接收 ReadResponse 的回调类型。
SnapshotSelectUICallback typedef
std::function< void(const SnapshotSelectUIResponse &)>
定义可以从 ShowSelectUIOperation 接收 SnapshotSelectUIResponse 的回调。

公共函数

Commit(const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > data, CommitCallback callback)
void
异步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。
CommitBlocking(const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
同步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。
CommitBlocking(Timeout timeout, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
同步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。
Delete(const SnapshotMetadata & snapshot_metadata)
void
删除指定的快照。
FetchAll(FetchAllCallback callback)
void
异步加载当前已登录玩家的所有快照数据。
FetchAll(DataSource data_source, FetchAllCallback callback)
void
异步加载当前已登录玩家的所有快照数据。
FetchAllBlocking()
同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse
FetchAllBlocking(DataSource data_source)
同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse
FetchAllBlocking(Timeout timeout)
同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse
FetchAllBlocking(DataSource data_source, Timeout timeout)
同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse
GetMaxSize(MaxSizeCallback callback) const
void
异步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位)。
GetMaxSizeBlocking() const
同步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位),直接返回 MaxSizeResponse
GetMaxSizeBlocking(Timeout timeout) const
同步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位),直接返回 MaxSizeResponse
Open(const std::string & file_name, SnapshotConflictPolicy conflict_policy, OpenCallback callback)
void
异步打开具有指定名称的快照。
Open(DataSource data_source, const std::string & file_name, SnapshotConflictPolicy conflict_policy, OpenCallback callback)
void
已弃用。 data_source 会被忽略。请改用 Open(file_name, conflict_policy, callback)
异步打开具有指定名称的快照。
OpenBlocking(const std::string & file_name, SnapshotConflictPolicy conflict_policy)
同步打开具有指定名称的快照。
OpenBlocking(Timeout timeout, const std::string & file_name, SnapshotConflictPolicy conflict_policy)
同步打开具有指定名称的快照。
OpenBlocking(DataSource data_source, const std::string & file_name, SnapshotConflictPolicy conflict_policy) 已弃用。 data_source 会被忽略。请改用 OpenBlocking(file_name, conflict_policy)
同步打开具有指定名称的快照。
OpenBlocking(DataSource data_source, Timeout timeout, const std::string & file_name, SnapshotConflictPolicy conflict_policy) 已弃用。 data_source 会被忽略。请改用 OpenBlocking(timeout, file_name, conflict_policy)
同步打开具有指定名称的快照。
Read(const SnapshotMetadata & snapshot_metadata, ReadCallback callback)
void
从磁盘中异步读取快照,并将其复制到内存中。
ReadBlocking(const SnapshotMetadata & snapshot_metadata)
从磁盘中同步读取快照,并将其复制到内存中。
ReadBlocking(Timeout timeout, const SnapshotMetadata & snapshot_metadata)
从磁盘中同步读取快照并将其复制到内存中。
ResolveConflict(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, OpenCallback callback)
void
使用所提供快照中的数据异步解决冲突。
ResolveConflict(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents, OpenCallback callback)
void
使用提供的数据异步解决冲突。
ResolveConflictBlocking(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata)
使用所提供快照中的数据同步解决冲突。
ResolveConflictBlocking(const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
使用提供的数据同步解决冲突。
ResolveConflictBlocking(Timeout timeout, const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata)
使用所提供快照中的数据同步解决冲突。
ResolveConflictBlocking(Timeout timeout, const std::string & conflict_id, const SnapshotMetadata & snapshot_metadata, const SnapshotMetadataChange & metadata_change, std::vector< uint8_t > contents)
使用提供的数据同步解决冲突。
ShowSelectUIOperation(bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title, SnapshotSelectUICallback callback)
void
异步显示快照界面,允许玩家选择快照或请求新快照。
ShowSelectUIOperationBlocking(Timeout timeout, bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title)
ShowSelectUIOperation 的屏蔽版本。
ShowSelectUIOperationBlocking(bool allow_create, bool allow_delete, uint32_t max_snapshots, const std::string & title)
ShowSelectUIOperationBlocking 的过载,使用默认超时期为 10 年。

结构体

gpg::SnapshotManager::CommitResponse

保留更新快照的数据以及响应状态。

gpg::SnapshotManager::FetchAllResponse

保留所有快照的所有数据以及响应状态。

gpg::SnapshotManager::MaxSizeResponse

保留快照数据和快照封面图片的大小上限。

gpg::SnapshotManager::OpenResponse

保存特定请求快照的数据以及响应状态。

gpg::SnapshotManager::ReadResponse

读取快照读取操作返回的响应状态和快照数据。

gpg::SnapshotManager::SnapshotSelectUIResponse

DataResponseStatus,用于 ShowSelectUIOperation 操作。

公共类型

CommitCallback

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

定义接收 CommitResponse 的回调类型。

此回调类型提供给下面的 Commit(*)ResolveConflict(*) 函数。

FetchAllCallback

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

定义接收 FetchAllResponse 的回调类型。

此回调类型会提供给以下 FetchAll(*) 函数。

MaxSizeCallback

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

定义接收 MaxSizeResponse 的回调类型。

系统会向 GetMaxSize 提供此回调类型。

OpenCallback

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

定义接收 OpenResponse 的回调类型。

此回调类型会提供给以下 Open(*) 函数。

ReadCallback

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

定义接收 ReadResponse 的回调类型。

此回调类型会提供给以下 Read(*) 函数。

SnapshotSelectUICallback

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

定义可以从 ShowSelectUIOperation 接收 SnapshotSelectUIResponse 的回调。

公共函数

提交

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

异步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。

在操作完成时调用提供的 CommitCallback

CommitBlocking

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

同步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。

CommitBlocking

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

同步提交提供给快照的数据,并使用提供的元数据对象更新快照的元数据。

以毫秒为单位指定 timeout

删除

void Delete(
  const SnapshotMetadata & snapshot_metadata
)

删除指定的快照。

这将在本地和服务器上删除快照的数据。

FetchAll

void FetchAll(
  FetchAllCallback callback
)

异步加载当前已登录玩家的所有快照数据。

在操作完成时调用提供的 FetchAllCallback。如果未指定 data_source,则此函数调用等同于调用 FetchAll(DataSource data_source, FetchAllCallback callback),并将 data_source 指定为 CACHE_OR_NETWORK.

FetchAll

void FetchAll(
  DataSource data_source,
  FetchAllCallback callback
)

异步加载当前已登录玩家的所有快照数据。

在操作完成时调用提供的 FetchAllCallback。将 data_source 指定为 CACHE_OR_NETWORKNETWORK_ONLY

FetchAllBlocking

FetchAllResponse FetchAllBlocking()

同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse

如果 data_sourcetimeout 均不指定,则此函数调用等同于调用 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout),其中 data_source 指定为 CACHE_OR_NETWORKtimeout 指定为 10 年。

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  DataSource data_source
)

同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse

data_source 指定为 CACHE_OR_NETWORKNETWORK_ONLY。如果未指定 timeout,则此函数调用等同于调用 FetchAllBlocking FetchAllResponse(DataSource data_source, Timeout timeout),使用指定的 data_source 值和 timeout 指定为 10 年。

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  Timeout timeout
)

同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse

以毫秒为单位指定 timeout。如果未指定 data_source,此函数调用等同于调用 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout),其中 data_source 指定为 CACHE_OR_NETWORKtimeout 包含您指定的值。

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  DataSource data_source,
  Timeout timeout
)

同步加载当前已登录玩家的所有快照数据,直接返回 FetchAllResponse

data_source 指定为 CACHE_OR_NETWORKNETWORK_ONLY。以毫秒为单位指定 timeout

GetMaxSize

void GetMaxSize(
  MaxSizeCallback callback
) const 

异步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位)。

在操作完成时调用提供的 MaxSizeCallback

每个快照的数据大小上限至少为 3 MB。未来可能会增加。

每个快照封面图片的最大数据大小保证至少为 800 KB。未来可能会增加。

GetMaxSizeBlocking

MaxSizeResponse GetMaxSizeBlocking() const 

同步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位),直接返回 MaxSizeResponse

每个快照的数据大小上限至少为 3 MB。未来可能会增加。

每个快照封面图片的最大数据大小保证至少为 800 KB。未来可能会增加。

GetMaxSizeBlocking

MaxSizeResponse GetMaxSizeBlocking(
  Timeout timeout
) const 

同步获取每个快照的最大数据大小和最大封面图片大小(以字节为单位),直接返回 MaxSizeResponse

每个快照的数据大小上限至少为 3 MB。未来可能会增加。

每个快照封面图片的最大数据大小保证至少为 800 KB。未来可能会增加。

以毫秒为单位指定 timeout

打开

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

异步打开具有指定名称的快照。

如果指定的快照尚不存在,系统将创建该快照。在操作完成时调用提供的 OpenCallback

快照名称必须介于 1 到 100 个非网址预留字符(a-z、A-Z、0-9 或符号“-”“.”“_”或“~”)之间。

在当前设备上,如果其他设备在加载快照与提交快照之间又提交了快照,就可能发生冲突。您必须解决这些冲突。如需详细了解冲突,请参阅上文的 OpenResponse

conflict_policy 可以是下列值之一:

SnapshotConflictPolicy::MANUAL - 如果存在冲突,则响应状态为 OpenResponse::VALID_WITH_CONFLICT。您必须使用 SnapshotManager::ResolveConflict 解决冲突。您可能会看到连续出现多个冲突的情况,因此请在每次调用 Open 时进行检查。只有这项政策才会发生冲突。其余的句柄是为您代劳。此政策可确保用户对游戏存档状态所做的更改不会丢失。

SnapshotConflictPolicy::LONGEST_PLAYTIME - 如果存在冲突,将使用游戏时间值最大的快照。如果游戏时间长度可以合理代表“最佳”游戏存档,则此政策是一个不错的选择。请注意,您必须在保存游戏时使用 SnapshotMetadataChange::Builder::SetPlayedTime(),此政策才有意义。

SnapshotConflictPolicy::LAST_KNOWN_GOOD - 如果存在冲突,则将使用基础快照。如果您的游戏要求快照数据的稳定性,则此政策是一个合理的选择。此政策可确保播放器只会看到未出现争议的写入,从而保证所有客户端都能收敛。注意:之前 SnapshotManager::BASE_WINS

SnapshotConflictPolicy::MOST_RECENTLY_MODIFIED - 发生冲突时,系统将使用遥控器。如果您的游戏可以容忍玩家在多台设备上破坏自己的更改,此政策是一个合理的选择。由于此政策会盲目选择最新数据,因此玩家的更改可能会丢失。注意:之前 SnapshotManager::REMOTE_WINS

SnapshotConflictPolicy::HIGHEST_PROGRESS如果发生冲突,将使用进度值最高的快照。如果数量相等,则会选择最近一次的已知良好快照。如果您的游戏使用快照的进度值来确定最佳游戏存档,则此政策是一个不错的选择。请注意,您必须在保存游戏时使用 SnapshotMetadataChange::Builder::SetPlayedTime(),此政策才有意义。

打开

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

异步打开具有指定名称的快照。

已弃用。 data_source 会被忽略。请改用 Open(file_name, conflict_policy, callback)

OpenBlocking

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

同步打开具有指定名称的快照。

如果指定的快照尚不存在,系统将创建该快照。

如需了解详情,请参阅 Open

OpenBlocking

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

同步打开具有指定名称的快照。

如果指定的快照尚不存在,系统将创建该快照。

以毫秒为单位指定 timeout

如需了解详情,请参阅 Open

OpenBlocking

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

同步打开具有指定名称的快照。

已弃用。 data_source 会被忽略。请改用 OpenBlocking(file_name, conflict_policy)

OpenBlocking

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

同步打开具有指定名称的快照。

已弃用。 data_source 会被忽略。请改用 OpenBlocking(timeout, file_name, conflict_policy)

读取

void Read(
  const SnapshotMetadata & snapshot_metadata,
  ReadCallback callback
)

从磁盘中异步读取快照,并将其复制到内存中。

为了便于修改,数据将通过值传回。每次调用此函数都会引发完全读取。这意味着,通常最好只读取一次快照。在操作完成时调用提供的 ReadCallback

ReadBlocking

ReadResponse ReadBlocking(
  const SnapshotMetadata & snapshot_metadata
)

从磁盘中同步读取快照,并将其复制到内存中。

为了便于修改,数据将通过值传回。每次调用此函数都会引发完全读取。这意味着,通常最好只读取一次快照。如果未指定 timeout,则此函数调用等同于调用 ReadBlocking ReadBlocking(Timeout timeout, const SnapshotMetadata& snapshot_metadata),其中 timeout 指定为 10 年。

ReadBlocking

ReadResponse ReadBlocking(
  Timeout timeout,
  const SnapshotMetadata & snapshot_metadata
)

从磁盘中同步读取快照并将其复制到内存中。

为了便于修改,数据将通过值传回。每次调用都会执行一次完整读取,因此通常只读取一次快照。以毫秒为单位指定 timeout

ResolveConflict

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

使用所提供快照中的数据异步解决冲突。

这会使用指定的快照替换服务器上的数据。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

在操作完成时调用提供的 OpenCallback

ResolveConflict

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

使用提供的数据异步解决冲突。

这会将服务器上的数据替换为指定的元数据更改和 contents。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

未包含在元数据更改中的值将解析为服务器上当前存在的版本。

请注意,contents 的总大小不得超过 GetMaxSize 提供的 maxDataSize

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

在操作完成时调用提供的 OpenCallback

ResolveConflictBlocking

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

使用所提供快照中的数据同步解决冲突。

这会使用指定的快照替换服务器上的数据。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

ResolveConflictBlocking

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

使用提供的数据同步解决冲突。

这会将服务器上的数据替换为指定的元数据更改和 contents。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

未包含在元数据更改中的值将解析为服务器上当前存在的版本。

请注意,contents 的总大小不得超过 GetMaxSize 提供的 maxDataSize

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

ResolveConflictBlocking

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

使用所提供快照中的数据同步解决冲突。

这会使用指定的快照替换服务器上的数据。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

以毫秒为单位指定 timeout

ResolveConflictBlocking

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

使用提供的数据同步解决冲突。

这会将服务器上的数据替换为指定的元数据更改和 contents。请注意,此操作本身可能会导致冲突,在这种情况下,应重复解决。

未包含在元数据更改中的值将解析为服务器上当前存在的版本。

请注意,contents 的总大小不得超过 GetMaxSize 提供的 maxDataSize

如果此方法的快照已提交或未通过 Open 打开,则调用此方法会失败,并显示 BaseStatus::ERROR_INTERNAL 状态。

以毫秒为单位指定 timeout

ShowSelectUIOperation

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

异步显示快照界面,允许玩家选择快照或请求新快照。

完成后,系统会通过 SnapshotSelectUICallback 返回所选快照或新的快照请求。

ShowSelectUIOperationBlocking

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

ShowSelectUIOperation 的屏蔽版本。

允许调用方指定超时(以毫秒为单位)。在指定的时间过后,该函数会返回 ERROR_TIMEOUT

ShowSelectUIOperationBlocking

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

ShowSelectUIOperationBlocking 的过载,使用默认超时期为 10 年。