Skip to main content

XGameSaveInitializeProviderAsync

以异步方式提供并初始化 XGameSave Provider 句柄。

语法

参数

requestingUser   _In_
类型:XUserHandle
XBOX Live 用户的句柄。 configurationId   _In_z_
类型:char*
服务配置 ID (SCID)。 syncOnDemand   _In_
类型:bool
当为 true 时,syncOnDemand 仅在需要时从服务下载数据。如果设备处于离线状态,则不起作用。 设置为 true 可能会导致显示同步进度 UI。 async   _In_
类型:XAsyncBlock*
包含异步调用的信息。这包括调用上下文以及对 XGameSaveInitializeProviderResult 函数的调用。

返回值

类型:HRESULT 函数结果。

备注

在使用其他 XGameSave API 之前必须成功调用此函数。
XGameSave API 要求你的游戏正确配置其游戏 ID 和服务配置 ID (SCID)
才能正常工作。有关这些必需 ID 的详细信息,请参阅为 XBOX Live 开发设置沙盒。你的游戏必须在合作伙伴中心为 XBOX Live 启用。
如果你没有正确配置 SCID 和游戏 ID,则你的 XSaveGame API 调用将失败并返回以下错误代码: E_GS_NO_ACCESS - 0x80830002 - 由于游戏无权访问容器存储空间,因此操作失败。 得到的 XGameSaveProviderHandle 是从 XGameSaveInitializeProviderResult 函数获取的。你将使用此句柄来 访问你的 XGameSaveProvider 当在调用此 API 时将 syncOnDemand 设置为 true 时,从调用方的角度看它的行为相同,但会导致 API 的其余部分出现 某些行为差异。SyncOnDemand XGameSaveProvider 仅在需要时从服务下载数据,但这也会带来一些缺点,即在这种情况下任何容器操作可能会延迟, 并且此延迟可能导致向用户显示某些 UX 以指示同步进度。使用以下任一方法都可以 强制同步: 另一个缺点是,如果设备处于离线状态或存在连接问题,则无法访问容器。 ##示例
游戏不能混合使用 XGameSaveFiles 和 XGameSave。游戏必须选择要使用的云保存系统。 如果游戏正在使用 XGameSaveFiles 且随后调用 XGameSaveInitializeProvider,则将出错 并返回 E_GS_PROVIDER_MISMATCH。同样,如果游戏正在使用 XGameSave 且随后调用 XGameSaveFilesGetFolderWithUiAsync, 也将出错并返回 E_GS_PROVIDER_MISMATCH。

要求

标头: XGameSave.h 库: xgameruntime.lib 支持的平台: Windows、XBOX One 系列主机和 XBOX Series 主机

概念性文档

另请参阅

XGameSave
XGameSaveInitializeProviderResult
XGameSaveInitializeProvider
调试游戏保存
最后修改于 2026年8月24日