> ## 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-CN/reference/system/xgamesave/functions/xgamesaveblobinfocallback.md) | 用于检索 [XGameSaveEnumerateBlobInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo.md) 结果的回调函数。 |
| [XGameSaveCloseContainer](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveclosecontainer.md) | 关闭 XGameSaveContainer。 |
| [XGameSaveCloseProvider](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavecloseprovider.md) | 释放 XGameSaveProvider 持有的资源。 |
| [XGameSaveCloseUpdate](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavecloseupdate.md) | 关闭 XGameSaveUpdate。 |
| [XGameSaveContainerInfoCallback](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavecontainerinfocallback.md) | 对 [XGameSaveGetContainerInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md) 的调用的回调函数。 |
| [XGameSaveCreateContainer](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavecreatecontainer.md) | 创建一个 XGameSaveContainer 句柄。 |
| [XGameSaveCreateUpdate](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavecreateupdate.md) | 创建一个更新，稍后将通过调用 [XGameSaveSubmitUpdate](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitupdate.md) 提交。 |
| [XGameSaveDeleteContainer](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavedeletecontainer.md) | 从云存储中删除 XGameSaveContainer。 |
| [XGameSaveDeleteContainerAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavedeletecontainerasync.md) | 异步删除 XGameSaveContainer。 |
| [XGameSaveDeleteContainerResult](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavedeletecontainerresult.md) | 检索 [XGameSaveDeleteContainerAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavedeletecontainerasync.md) 调用的结果，使用此函数检查调用是否成功。 |
| [XGameSaveEnumerateBlobInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo.md) | 检索 XGameSaveContainer 内容的 Blob 信息。 |
| [XGameSaveEnumerateBlobInfoByName](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveenumerateblobinfobyname.md) | 检索 XGameSaveContainer 内容的 Blob 信息，仅限于与 blobNamePrefix 参数具有相同前缀的 Blob。 |
| [XGameSaveEnumerateContainerInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo.md) | 检索 XGameSaveProvider 的容器信息。 |
| [XGameSaveEnumerateContainerInfoByName](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfobyname.md) | 检索 XGameSaveProvider 的容器信息。 |
| [XGameSaveGetContainerInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md) | 检索 XGameSaveProvider 中容器的信息。 |
| [XGameSaveGetRemainingQuota](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetremainingquota.md) | 返回可使用 XGameSave API 存储的数据量。 |
| [XGameSaveGetRemainingQuotaAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetremainingquotaasync.md) | 异步返回可使用 XGameSave API 存储的数据量。 |
| [XGameSaveGetRemainingQuotaResult](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetremainingquotaresult.md) | 检索 [XGameSaveGetRemainingQuotaAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavegetremainingquotaasync.md) 函数的结果。 |
| [XGameSaveInitializeProvider](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md) | 提供并初始化 XGameSave Provider 句柄。 |
| [XGameSaveInitializeProviderAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md) | 以异步方式提供并初始化 XGameSave Provider 句柄。 |
| [XGameSaveInitializeProviderResult](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult.md) | 包含 [XGameSaveInitializeProviderAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md) 调用的结果。 |
| [XGameSaveReadBlobData](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavereadblobdata.md) | 读取容器的 Blob 数据。 |
| [XGameSaveReadBlobDataAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavereadblobdataasync.md) | 以异步方式从 XGameSaveContainer 中读取 XGameSaveBlob 数据。 |
| [XGameSaveReadBlobDataResult](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavereadblobdataresult.md) | 检索 [XGameSaveReadBlobDataAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavereadblobdataasync.md) 调用的结果。 |
| [XGameSaveSubmitBlobDelete](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitblobdelete.md) | 将删除操作添加到游戏存档 XGameSaveUpdate。 |
| [XGameSaveSubmitBlobWrite](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitblobwrite.md) | 将写入操作添加到 XGameSaveUpdate。 |
| [XGameSaveSubmitUpdate](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitupdate.md) | 向 XGameSave 服务提交更新。更新容器内的 Blob。 |
| [XGameSaveSubmitUpdateAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitupdateasync.md) | 以异步方式向 XGameSave 服务提交更新。更新容器内的 Blob。 |
| [XGameSaveSubmitUpdateResult](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitupdateresult.md) | 检索 [XGameSaveSubmitUpdateAsync](https://docs.xbox.com/zh-CN/reference/system/xgamesave/functions/xgamesavesubmitupdateasync.md) 调用的结果。 |

## 结构

| 结构 | 说明 |
| - | - |
| [XGameSaveBlob](https://docs.xbox.com/zh-CN/reference/system/xgamesave/structs/xgamesaveblob.md) | XGameSave 存储的信息单位。位于 XGameSaveContainer 内。 |
| [XGameSaveBlobInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/structs/xgamesaveblobinfo.md) | 关于 XGameSaveBlob 的信息。 |
| [XGameSaveContainerInfo](https://docs.xbox.com/zh-CN/reference/system/xgamesave/structs/xgamesavecontainerinfo.md) | 关于 XGameSaveContainer 的信息。 |

## 错误代码

XGameSave API 可能返回以下错误代码。完整列表请参阅[错误代码](https://docs.xbox.com/zh-CN/reference/errorcodes.md)。有关详细的故障排除指南，请参阅[游戏存档调试](https://docs.xbox.com/zh-CN/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 | 未正确为连接存储配置游戏。请检查 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-CN/build/core-features/common/game-save/game-saves-overview.md)
* [XGameSave 指南](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/xgamesave.md)
* [游戏存档调试](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-debugging.md)

## 另请参阅

[系统 API 参考](https://docs.xbox.com/zh-CN/reference/system/gc-reference-system-toc.md)


## Related topics

- [XGameSave API 概述](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/xgamesave.md)
- [游戏存档调试](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-debugging.md)
- [游戏存档存储系统](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-storage-systems.md)
- [游戏存档工具](https://docs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-tools.md)
- [XGameSave Wrapper 参考（API 内容）](https://docs.xbox.com/zh-CN/reference/system/Wrappers/xgamesave_wrapper_members.md)