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
<ph type="x-smartling-placeholder"></ph> 已弃用。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) <ph type="x-smartling-placeholder"></ph> 已弃用。data_source 会被忽略。请改用 OpenBlocking(file_name, conflict_policy)
同步打开具有给定名称的快照。
OpenBlocking(DataSource data_source, Timeout timeout, const std::string & file_name, SnapshotConflictPolicy conflict_policy) <ph type="x-smartling-placeholder"></ph> 已弃用。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

用于 ShowSelectUIOperation 操作的 DataResponseStatus

公共类型

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_source,也未指定 timeout,则此函数调用等同于调用 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
)

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

<ph type="x-smartling-placeholder"></ph> 已弃用。data_source 会被忽略。请改用 Open(file_name, conflict_policy, callback)

OpenBlocking

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

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

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

如需了解详情,请参阅打开

OpenBlocking

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

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

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

以毫秒为单位指定 timeout

如需了解详情,请参阅打开

OpenBlocking

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

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

<ph type="x-smartling-placeholder"></ph> 已弃用。data_source 会被忽略。请改用 OpenBlocking(file_name, conflict_policy)

OpenBlocking

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

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

<ph type="x-smartling-placeholder"></ph> 已弃用。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 年。