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

針對 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_sourcetimeout,會導致這個函式呼叫等同於呼叫 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_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
)

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

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

詳情請參閱開啟

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
)

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

完成後,系統會透過 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 年。