Skip to main content

XGameSaveInitializeProvider

提供并初始化 XGameSave Provider 句柄。

语法

参数

requestingUser   _In_
类型:XUserHandle
XBOX Live 用户的句柄。 configurationId   _In_z_
类型:char*
服务配置 ID (SCID)。 syncOnDemand   _In_
类型:bool
当为 true 时,syncOnDemand 仅在需要时从服务下载数据。如果设备处于离线状态,则不起作用。 设置为 true 可能会导致显示同步进度 UI。 provider   _Outptr_result_nullonfailure_
类型:XGameSaveProviderHandle*
要创建的 XGameSave Provider 的句柄。

返回值

类型:HRESULT 函数结果。

常见错误

  • E_GS_USER_CANCELED
  • E_GS_USER_NOT_REGISTERED_IN_SERVICE
  • E_GS_NO_ACCESS
  • E_GS_NO_SERVICE_CONFIGURATION
最常返回的错误是 E_OUTOFMEMORY、E_INVALIDARG。

备注

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

要求

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

概念性文档

另请参阅

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