XGameSaveSubmitUpdate

XGameSave サービスに更新を送信します。 コンテナー内の BLOB を更新します。

構文

HRESULT XGameSaveSubmitUpdate(  
         XGameSaveUpdateHandle updateContext  
)  

パラメーター

updateContext _In_
型: XGameSaveUpdateHandle

更新する XGameSaveUpdate に対するハンドル。

戻り値

型: HRESULT

関数の結果です。

一般的なエラー

• E_GS_INVALID_CONTAINER_NAME
• E_GS_OUT_OF_LOCAL_STORAGE
• E_GS_UPDATE_TOO_BIG
• E_GS_QUOTA_EXCEEDED
• E_GS_CONTAINER_NOT_IN_SYNC
• E_GS_CONTAINER_SYNC_FAILED
• E_GS_HANDLE_EXPIRED

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。 詳細については、「時間依存のスレッド」を参照してください。

この呼び出しを行う前に、XGameSaveCreateUpdate の呼び出しが成功している必要があります。

この API のストレージ部分は、ゲームから永続ストレージに、安全で信頼できるトランザクション方式でデータを簡単に転送するように設計されています。 コンテナーへのデータのバックアップには常に整合性が必要であり、そのため操作全体がアトミックに成功または失敗する必要があります。 一部の BLOB データがコンテナー内の他のデータと整合しなくなる部分的な更新が行われないようにする必要があります。 これを実行するため、BLOB の書き込みと削除が送信される更新コンテキストが提供され、その準備ができるとコンテキスト全体が送信されます。 実際には、次のようになります。

XGameSaveUpdate には、XGameSaveSubmitBlobWrite と XGameSaveSubmitBlobDelete によって、コンテナー内の BLOB に対して実行される書き込みおよび削除の操作が設定されます。 更新は、XGameSaveSubmitUpdate を呼び出すことによって完了されます。

XGameSaveUpdate が終了したら、XGameSaveCloseUpdate メソッドを使用してそれを閉じます。

次の C++ サンプルでは、XGameSave の同期更新を示します。

// SYNC Write - should not be called on a time sensitive thread 
//              as this will block until the operation is complete 
void Sample::_SaveDataSync(const char* containerName, const char* containerDisplayName) 
{ 
    HRESULT hr; 
    XGameSaveContainerHandle containerContext; 
    XGameSaveUpdateHandle updateContext; 
  
    hr = XGameSaveCreateContainer(_provider, containerName, &containerContext); 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveCreateUpdate(containerContext, containerDisplayName, &updateContext); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "WorldState", _worldState.data(), _worldState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "PlayerState", _playerState.data(), _playerState.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitBlobWrite(updateContext, "PlayerInventory", _playerInventory.data(), _playerInventory.size()); 
    } 
    if (SUCCEEDED(hr)) 
    { 
        if (_clearLevelProgress) 
        { 
            hr = XGameSaveSubmitBlobDelete(updateContext, "LevelProgress"); 
        } 
    } 
  
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveSubmitUpdate(updateContext); 
    } 
  
    if (updateContext) 
    { 
        XGameSaveCloseUpdate(updateContext); 
    } 
    if (containerContext) 
    { 
        XGameSaveCloseContainer(containerContext); 
    } 
  
    _HandleContainerUpdateErrors(hr); 
} 
  
  
void Sample::_HandleContainerUpdateErrors(HRESULT hr) 
{ 
    switch (hr) 
    { 
    case E_GS_INVALID_CONTAINER_NAME: 
        // tried to access a container with an invalid name 
        break; 
    case E_GS_OUT_OF_LOCAL_STORAGE: 
        // storage location is full, let the user know that saves won't work till this is fixed 
        break; 
    case E_GS_UPDATE_TOO_BIG: 
        // the blob that we provided was too big, can't be larger than GS_MAX_BLOB_SIZE 
        break; 
    case E_GS_QUOTA_EXCEEDED: 
        // the update we did was larger than our overall quota, need to track that! (see XGameSaveQueryRemainingQuota & XGameSaveQueryRemainingQuotaAsync) 
        break; 
    case E_GS_CONTAINER_NOT_IN_SYNC: 
    case E_GS_CONTAINER_SYNC_FAILED: 
        // need to sync and we are offline ? 
        break; 
    case E_GS_HANDLE_EXPIRED: 
        // need to re-initialize since another device has taken 
        // ownership while we were suspended and/or busy 
        break; 
    } 
} 

要件

ヘッダー: XGameSave.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

関連項目

XGameSave
XGameSaveCreateUpdate
XGameSaveSubmitBlobWrite
XGameSaveSubmitBlobDelete
XGameSaveCloseUpdateGame save errors