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
以非同步方式顯示快照 UI，讓玩家選取快照或要求新的快照。
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 年。

Structs
gpg::SnapshotManager::CommitResponse

將更新快照的資料與回應狀態保留下來。
gpg::SnapshotManager::FetchAllResponse

保存所有快照的所有資料，以及回應狀態。
gpg::SnapshotManager::MaxSizeResponse

保留快照資料和快照封面圖片的大小上限。
gpg::SnapshotManager::OpenResponse

保留特定要求快照的資料，以及回應狀態。
gpg::SnapshotManager::ReadResponse

這個外掛程式能讀取快照讀取作業傳回的回應狀態和快照資料。
gpg::SnapshotManager::SnapshotSelectUIResponse

ShowSelectUIOperation 作業的 Data 和 ResponseStatus。

公開類型

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_NETWORK 或 NETWORK_ONLY。

FetchAllBlocking

FetchAllResponse FetchAllBlocking()

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

不指定 data_source 和 timeout 會造成這個函式呼叫等同於呼叫 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout)，其中 data_source 已指定為 CACHE_OR_NETWORK，timeout 指定為 10 年。

FetchAllBlocking

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

FetchAllBlocking

FetchAllResponse FetchAllBlocking(
  Timeout timeout
)

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

指定 timeout (以毫秒為單位)。如未指定 data_source，這個函式呼叫會等同於呼叫 FetchAllResponse FetchAllBlocking(DataSource data_source, Timeout timeout)，其中 data_source 指定為 CACHE_OR_NETWORK，timeout 則指定為包含指定值。

FetchAllBlocking

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。日後可能會增加。

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
)

同步開啟指定名稱的快照。

如果指定的快照不存在，系統會建立該快照。

詳情請參閱開啟。

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
)

同步開啟指定名稱的快照。

已淘汰，，瞭解如何調查及移除這項存取權。 已忽略 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
)

以非同步方式顯示快照 UI，讓玩家選取快照或要求新的快照。

建立完成之後，系統會透過 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 年。