> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameSaveSubmitUpdate

> XGameSaveSubmitUpdate

# XGameSaveSubmitUpdate

將更新提交至 XGameSave 服務。更新容器內的 Blob。

## 語法

```cpp theme={null}
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

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

您必須先成功呼叫 [XGameSaveCreateUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavecreateupdate)，才能進行此呼叫。

此 API 的儲存部分旨在以安全、可靠且交易式的方式，輕鬆地將資料從遊戲傳輸到永續性儲存體。我們希望確保容器的支援資料一律保持一致，因此希望整個作業以不可部分完成的方式成功或失敗。我們不希望發生部分更新，導致某些 Blob 資料與容器內的其他資料不一致。為了達成此目的，我們提供一個更新內容，Blob 的寫入和刪除會提交至此內容，待其準備就緒時再提交整個內容。實際上看起來如下：

XGameSaveUpdate 會透過 [XGameSaveSubmitBlobWrite](/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobwrite) 和 [XGameSaveSubmitBlobDelete](/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobdelete)，填入要對容器內 Blob 執行的寫入和刪除動作。呼叫 [XGameSaveSubmitUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdate) 即可完成更新。

當您使用完 **XGameSaveUpdate** 時，請使用 [XGameSaveCloseUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavecloseupdate) 方法將其關閉。

下列 C++ 範例示範同步 XGameSave 更新。

```cpp theme={null}
// 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 主機

## 概念文件

* [偵錯遊戲存檔](/zh-TW/build/core-features/common/game-save/game-saves-debugging)
* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

[XGameSave](/zh-TW/reference/system/xgamesave/xgamesave_members)\
[XGameSaveCreateUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavecreateupdate)\
[XGameSaveSubmitBlobWrite](/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobwrite)\
[XGameSaveSubmitBlobDelete](/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobdelete)\
[XGameSaveCloseUpdate](/zh-TW/reference/system/xgamesave/functions/xgamesavecloseupdate)
[偵錯遊戲存檔](/zh-TW/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveSubmitUpdate](/reference/system/xgamesave/functions/xgamesavesubmitupdate.md)
- [XGameSaveCreateUpdate](/reference/system/xgamesave/functions/xgamesavecreateupdate.md)
- [XGameSaveSubmitBlobDelete](/reference/system/xgamesave/functions/xgamesavesubmitblobdelete.md)
- [XGameSaveSubmitBlobWrite](/reference/system/xgamesave/functions/xgamesavesubmitblobwrite.md)
- [XGameSaveSubmitUpdateAsync](/reference/system/xgamesave/functions/xgamesavesubmitupdateasync.md)