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

# XGameSave (API 內容)

> XGameSave

# XGameSave

XGameSave API 的設計目的是讓您能夠建立、載入、儲存和管理遊戲相關狀態。此實作與先前實作的主要差異在於，它將提供一個扁平 API，可存取非同步程式設計模型，讓呼叫端能夠控制 API 行為的執行緒處理和記憶體管理。

## 函式

| 函式 | 描述 |
| - | - |
| [XGameSaveBlobInfoCallback](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveblobinfocallback.md) | 用來擷取 [XGameSaveEnumerateBlobInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo.md) 結果的回呼函式。 |
| [XGameSaveCloseContainer](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveclosecontainer.md) | 關閉 XGameSaveContainer。 |
| [XGameSaveCloseProvider](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavecloseprovider.md) | 釋放 XGameSaveProvider 所保留的資源。 |
| [XGameSaveCloseUpdate](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavecloseupdate.md) | 關閉 XGameSaveUpdate。 |
| [XGameSaveContainerInfoCallback](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavecontainerinfocallback.md) | 對 [XGameSaveGetContainerInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md) 所進行之呼叫的回呼函式。 |
| [XGameSaveCreateContainer](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavecreatecontainer.md) | 建立 XGameSaveContainer 控制代碼。 |
| [XGameSaveCreateUpdate](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavecreateupdate.md) | 建立稍後將透過呼叫 [XGameSaveSubmitUpdate](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdate.md) 提交的更新。 |
| [XGameSaveDeleteContainer](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavedeletecontainer.md) | 從雲端儲存體刪除 XGameSaveContainer。 |
| [XGameSaveDeleteContainerAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavedeletecontainerasync.md) | 以非同步方式刪除 XGameSaveContainer。 |
| [XGameSaveDeleteContainerResult](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavedeletecontainerresult.md) | 擷取 [XGameSaveDeleteContainerAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavedeletecontainerasync.md) 呼叫的結果，請使用此函式檢查呼叫是否成功。 |
| [XGameSaveEnumerateBlobInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo.md) | 擷取 XGameSaveContainer 內容的 Blob 資訊。 |
| [XGameSaveEnumerateBlobInfoByName](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveenumerateblobinfobyname.md) | 擷取 XGameSaveContainer 內容的 Blob 資訊，僅限於與 blobNamePrefix 參數共用前置詞的 Blob。 |
| [XGameSaveEnumerateContainerInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo.md) | 擷取 XGameSaveProvider 的容器資訊。 |
| [XGameSaveEnumerateContainerInfoByName](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfobyname.md) | 擷取 XGameSaveProvider 的容器資訊。 |
| [XGameSaveGetContainerInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md) | 擷取 XGameSaveProvider 中容器的資訊。 |
| [XGameSaveGetRemainingQuota](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquota.md) | 傳回可使用 XGameSave API 儲存的資料量。 |
| [XGameSaveGetRemainingQuotaAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquotaasync.md) | 以非同步方式傳回可使用 XGameSave API 儲存的資料量。 |
| [XGameSaveGetRemainingQuotaResult](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquotaresult.md) | 擷取 [XGameSaveGetRemainingQuotaAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavegetremainingquotaasync.md) 函式的結果。 |
| [XGameSaveInitializeProvider](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md) | 提供並初始化 XGameSave Provider 控制代碼。 |
| [XGameSaveInitializeProviderAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md) | 以非同步方式提供並初始化 XGameSave Provider 控制代碼。 |
| [XGameSaveInitializeProviderResult](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult.md) | 包含 [XGameSaveInitializeProviderAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md) 呼叫的結果。 |
| [XGameSaveReadBlobData](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdata.md) | 讀取容器的 Blob 資料。 |
| [XGameSaveReadBlobDataAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdataasync.md) | 以非同步方式從 XGameSaveContainer 讀取 XGameSaveBlob 資料。 |
| [XGameSaveReadBlobDataResult](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdataresult.md) | 擷取 [XGameSaveReadBlobDataAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavereadblobdataasync.md) 呼叫的結果。 |
| [XGameSaveSubmitBlobDelete](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobdelete.md) | 將刪除動作新增至遊戲存檔 XGameSaveUpdate。 |
| [XGameSaveSubmitBlobWrite](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitblobwrite.md) | 將寫入動作新增至 XGameSaveUpdate。 |
| [XGameSaveSubmitUpdate](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdate.md) | 將更新提交至 XGameSave 服務。更新容器內的 Blob。 |
| [XGameSaveSubmitUpdateAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdateasync.md) | 以非同步方式將更新提交至 XGameSave 服務。更新容器內的 Blob。 |
| [XGameSaveSubmitUpdateResult](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdateresult.md) | 擷取 [XGameSaveSubmitUpdateAsync](https://docs.xbox.com/zh-TW/reference/system/xgamesave/functions/xgamesavesubmitupdateasync.md) 呼叫的結果。 |

## 結構

| 結構 | 描述 |
| - | - |
| [XGameSaveBlob](https://docs.xbox.com/zh-TW/reference/system/xgamesave/structs/xgamesaveblob.md) | XGameSave 儲存體的資訊單位。位於 XGameSaveContainer 內。 |
| [XGameSaveBlobInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/structs/xgamesaveblobinfo.md) | XGameSaveBlob 的相關資訊。 |
| [XGameSaveContainerInfo](https://docs.xbox.com/zh-TW/reference/system/xgamesave/structs/xgamesavecontainerinfo.md) | XGameSaveContainer 的相關資訊。 |

## 錯誤碼

XGameSave API 可能會傳回下列錯誤碼。如需完整清單，請參閱[錯誤碼](https://docs.xbox.com/zh-TW/reference/errorcodes.md)。如需詳細的疑難排解指引，請參閱[偵錯遊戲存檔](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-debugging.md)。

| 代碼 | 值 | 描述 |
| - | - | - |
| E\_GS\_INVALID\_CONTAINER\_NAME | 0x80830001 | 容器名稱無效。有效的容器名稱字元包括大寫/小寫字母、數字、底線和正斜線。 |
| E\_GS\_NO\_ACCESS | 0x80830002 | 作業失敗，因為遊戲無法存取容器儲存空間。請檢查 SCID 和 TitleId 是否已正確設定。 |
| E\_GS\_OUT\_OF\_LOCAL\_STORAGE | 0x80830003 | 裝置沒有足夠的儲存容量來儲存遊戲。 |
| E\_GS\_USER\_CANCELED | 0x80830004 | 使用者取消了其遊戲存檔的下載。 |
| E\_GS\_UPDATE\_TOO\_BIG | 0x80830005 | 存檔更新的大小過大。XGameSave 更新的總大小必須小於 GS\_MAX\_BLOB\_SIZE (16 MB)。 |
| E\_GS\_QUOTA\_EXCEEDED | 0x80830006 | 已超過此使用者的遊戲儲存配額。 |
| E\_GS\_PROVIDED\_BUFFER\_TOO\_SMALL | 0x80830007 | 提供給 API 的緩衝區太小。 |
| E\_GS\_BLOB\_NOT\_FOUND | 0x80830008 | 找不到指定的 Blob。 |
| E\_GS\_NO\_SERVICE\_CONFIGURATION | 0x80830009 | 遊戲未針對 Connected Storage 正確設定。請檢查 SCID 是否正確，以及遊戲是否已在 Partner Center 中設定。 |
| E\_GS\_CONTAINER\_NOT\_IN\_SYNC | 0x8083000A | 容器尚未同步。提交更新之前，請確定 XGameSave 容器已同步。 |
| E\_GS\_CONTAINER\_SYNC\_FAILED | 0x8083000B | 容器同步失敗。 |
| E\_GS\_USER\_NOT\_REGISTERED\_IN\_SERVICE | 0x8083000C | 使用者的 MSA 尚未成為 XBOX services 帳戶。 |
| E\_GS\_HANDLE\_EXPIRED | 0x8083000D | 函式所使用的控制代碼已過期，必須重新取得。 |
| E\_GS\_ASYNC\_FUNCTION\_REQUIRED | 0x8083000E | 此同步函式正在時間敏感執行緒上呼叫，有發生死結的風險。請改用非同步實作。 |
| E\_GS\_PROVIDER\_MISMATCH | 0x8083000F | 遊戲混用了 XGameSave 和 XGameSaveFiles 呼叫，這是不支援的。 |

## 概念文件

* [遊戲存檔概觀](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-overview.md)
* [XGameSave 指南](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/xgamesave.md)
* [偵錯遊戲存檔](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-debugging.md)

## 另請參閱

[系統 API 參考](https://docs.xbox.com/zh-TW/reference/system/gc-reference-system-toc.md)


## Related topics

- [XGameSave API 概觀](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/xgamesave.md)
- [Game Saves 偵錯](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-debugging.md)
- [Game Saves 工具](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-tools.md)
- [Game Saves 儲存系統](https://docs.xbox.com/zh-TW/build/core-features/common/game-save/game-saves-storage-systems.md)
- [XGameSave Wrapper 參考 (API 內容)](https://docs.xbox.com/zh-TW/reference/system/Wrappers/xgamesave_wrapper_members.md)