透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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)
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

Data 和 ResponseStatus 用於 ShowSelectUIOperation 作業。

公開類型

修訂版本回呼

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

定義接收 CommitResponse 的回呼類型。

此回呼類型會提供給下方的 Commit(*) 和 ResolveConflict(*) 函式。

擷取所有回呼

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

定義接收 FetchAllResponse 的回呼類型。

此回呼類型會提供給下方的 FetchAll(*) 函式。

大小上限

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

定義接收 MaxSizeResponse 的回呼類型。

此回呼類型會提供給 GetMaxSize。

OpenCallback

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

定義接收 OpenResponse 的回呼類型。

此回呼類型會提供給下方的 Open(*) 函式。

讀取回電

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

定義接收 ReadResponse 的回呼類型。

此回呼類型會提供給下方的 Read(*) 函式。

快照選取 UI 回呼

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。

修訂版本封鎖

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

同步提供提供給快照的資料，並使用提供的中繼資料物件更新快照的中繼資料。

修訂版本封鎖

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

同步提供提供給快照的資料，並使用提供的中繼資料物件更新快照的中繼資料。

以毫秒為單位指定 timeout。

刪除

void Delete(
  const SnapshotMetadata & snapshot_metadata
)

刪除指定的快照。

這項操作會在本機和伺服器上刪除快照的資料。

擷取全部

void FetchAll(
  FetchAllCallback callback
)

以非同步方式載入目前登入玩家的所有快照資料。

作業完成時呼叫所提供的 FetchAllCallback。未指定 data_source 會讓這個函式呼叫等同於呼叫 FetchAll(DataSource data_source, FetchAllCallback callback)，並將 data_source 指定為 CACHE_OR_NETWORK.

擷取全部

void FetchAll(
  DataSource data_source,
  FetchAllCallback callback
)

以非同步方式載入目前登入玩家的所有快照資料。

作業完成時呼叫所提供的 FetchAllCallback。將 data_source 指定為 CACHE_OR_NETWORK 或 NETWORK_ONLY。

擷取所有封鎖

FetchAllResponse FetchAllBlocking()

同步載入目前登入玩家的所有快照資料，直接傳回 FetchAllResponse。

如果未指定 data_source 和 timeout，這個函式呼叫就能呼叫 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout)，其中 data_source 指定為 CACHE_OR_NETWORK，timeout 則指定為 10 年。

擷取所有封鎖

FetchAllResponse FetchAllBlocking(
  DataSource data_source
)

同步載入目前登入玩家的所有快照資料，直接傳回 FetchAllResponse。

將 data_source 指定為 CACHE_OR_NETWORK 或 NETWORK_ONLY。不指定 timeout 使此功能呼叫等同呼叫 FetchAllBlocking FetchAllResponse(DataSource data_source, Timeout timeout)，指定 data_source 值，timeout 指定 10 年。

擷取所有封鎖

FetchAllResponse FetchAllBlocking(
  Timeout timeout
)

同步載入目前登入玩家的所有快照資料，直接傳回 FetchAllResponse。

以毫秒為單位指定 timeout。如未指定 data_source，這個函式呼叫就能呼叫 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout)，其中 data_source 指定為 CACHE_OR_NETWORK，而 timeout 則包含您指定的值。

擷取所有封鎖

FetchAllResponse FetchAllBlocking(
  DataSource data_source,
  Timeout timeout
)

同步載入目前登入玩家的所有快照資料，直接傳回 FetchAllResponse。

將 data_source 指定為 CACHE_OR_NETWORK 或 NETWORK_ONLY。以毫秒為單位指定 timeout。

GetMaxSize

void GetMaxSize(
  MaxSizeCallback callback
) const

非同步取得每個快照的資料大小上限和封面大小上限 (以位元組為單位)。

作業完成時呼叫所提供的 MaxSizeCallback。

保證每個快照的資料量上限為 3 MB。未來可能會增加。

每則快照的大小上限為 800 KB 以上的快照。未來可能會增加。

連結最高大小封鎖

MaxSizeResponse GetMaxSizeBlocking() const

同步取得最大快照的資料大小和最大快照大小 (以位元組為單位)，直接傳回 MaxSizeResponse。

保證每個快照的資料量上限為 3 MB。未來可能會增加。

每則快照的大小上限為 800 KB 以上的快照。未來可能會增加。

連結最高大小封鎖

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 - 如果發生衝突，系統會採用播放時間值最高的快照。如果遊戲長度是「最佳」儲存遊戲的合理 Proxy，建議您採用這項政策。請注意，儲存這項政策時，請務必使用 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)。

OpenBlock

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

以指定名稱開啟快照。

如果指定的快照不存在，就會加以建立。

詳情請參閱開啟。

OpenBlock

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

以指定名稱開啟快照。

如果指定的快照不存在，就會加以建立。

以毫秒為單位指定 timeout。

詳情請參閱開啟。

OpenBlock

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

以指定名稱開啟快照。

已淘汰， 系統會忽略 data_source。請改用 OpenBlocking(file_name, conflict_policy)。

OpenBlock

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。

唯讀封鎖

ReadResponse ReadBlocking(
  const SnapshotMetadata & snapshot_metadata
)

將磁碟讀取快照，然後再複製到記憶體。

資料會按值傳回，以利您修改。每次呼叫這個函式都會產生完整讀取。這通常，最好只讀取快照一次。未指定 timeout 會讓這個函式呼叫等同於呼叫 ReadBlocking ReadBlocking(Timeout timeout, const SnapshotMetadata& snapshot_metadata)，且 timeout 指定為 10 年。

唯讀封鎖

ReadResponse ReadBlocking(
  Timeout timeout,
  const SnapshotMetadata & snapshot_metadata
)

將磁碟的快照同步讀取並複製到記憶體。

資料會按值傳回，以利您修改。每次呼叫都會執行完整讀取，所以通常只會讀取一次。以毫秒為單位指定 timeout。

解決衝突問題

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

使用提供的快照資料，以非同步方式解決衝突問題。

這會以指定快照取代伺服器中的資料。請注意，這項作業可能會造成衝突本身，此時應會重複解決問題。

使用已提交或未透過 Open 開啟的快照呼叫此方法，將失敗，並顯示 BaseStatus::ERROR_INTERNAL 狀態。

作業完成時呼叫所提供的 OpenCallback。

解決衝突問題

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。

解決衝突封鎖問題

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

使用提供的快照資料，同步解決衝突問題。

這會以指定快照取代伺服器中的資料。請注意，這項作業可能會造成衝突本身，此時應會重複解決問題。

使用已提交或未透過 Open 開啟的快照呼叫此方法，將失敗，並顯示 BaseStatus::ERROR_INTERNAL 狀態。

解決衝突封鎖問題

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 狀態。

解決衝突封鎖問題

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

使用提供的快照資料，同步解決衝突問題。

這會以指定快照取代伺服器中的資料。請注意，這項作業可能會造成衝突本身，此時應會重複解決問題。

使用已提交或未透過 Open 開啟的快照呼叫此方法，將失敗，並顯示 BaseStatus::ERROR_INTERNAL 狀態。

以毫秒為單位指定 timeout。

解決衝突封鎖問題

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。

顯示選取 UI 作業

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

以非同步方式顯示快照使用者介面，讓玩家選取快照或要求新快照。

完成後，系統會透過 SnapshotSelectUICallback 傳回所選的快照或新的快照要求。

顯示選取 UIUI 作業封鎖

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

封鎖 ShowSelectUIOperation。

允許呼叫者以毫秒為單位指定逾時時間。經過指定的時間後，函式會傳回 ERROR_TIMEOUT。

顯示選取 UIUI 作業封鎖

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

ShowSelectUIOperationBlocking 超載，使用預設的 10 年逾時時間。