XGameSaveInitializeProvider
提供并初始化 XGameSave 提供程序句柄。
语法
HRESULT XGameSaveInitializeProvider(
XUserHandle requestingUser,
const char* configurationId,
bool syncOnDemand,
XGameSaveProviderHandle* 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 提供程序的句柄。
返回值
类型：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 - 操作失败，因为该游戏不具有访问容器存储空间的权限。
在 syncOnDemand 设置为 true 的情况下调用此 API 时，从调用方角度来说其行为完全相同，但它会导致其余 API 中的一些行为差异。 SyncOnDemandXGameSaveProvider 将仅在需要时从服务下载数据，但这同时也会带来某些缺点，就是在此情况下任何容器操作可能会延迟，并且此延迟可能导致某些 UX 显示给用户用于同步进度。 使用下列任何方法都可以强制同步：
- XGameSaveCreateUpdate
- XGameSaveEnumeratorBlobInfo
- XGameSaveEnumerateBlobInfoByName
- XGameSaveEnumerateContainerInfo
- XGameSaveEnumerateContainerInfoByName
另一个缺点是，如果设备脱机或存在连接问题，则无法访问改容器。 存在称为 XGameSaveInitializeProviderAsync 的此函数的异步版本
// SYNC Init - should not be called on time sensitive thread
// as this will block until the operation is complete
void Sample::_InitializeSync()
{
HRESULT hr;
XGameSaveProviderHandle provider = nullptr;
hr = XGameSaveInitializeProvider(this->_xalUser, "SERVICE_CONFIG_ID-DEADBEEF0123", false, &provider);
if (SUCCEEDED(hr))
{
this->_provider = provider;
}
else
{
_HandleInitializeErrors(this->_xalUser, hr);
}
}
// handle initialization errors
void Sample::_HandleInitializeErrors(XUserHandle userContext, HRESULT hr)
{
switch (hr)
{
case E_GS_USER_CANCELED:
printf("User %p canceled initialization hr=0x%08x\n", userContext, hr);
break;
case E_GS_USER_NOT_REGISTERED_IN_SERVICE:
printf("User %p has no service registration\n", userContext);
break;
/* NOTE These should only be seen if there is a configuration issue */
case E_GS_NO_ACCESS:
case E_GS_NO_SERVICE_CONFIGURATION:
printf("Problems with Service Configuration registration\n");
break;
case S_OK:
break;
default:
printf("Unknown initialization error for User %p hr=0x%08X\n", userContext, hr);
}
}
游戏不能将 XGameSaveFiles 与 XGameSave 混合使用。 游戏必须选择要使用的云存储系统。 如果游戏使用 XGameSaveFiles，并在以后调用 XGameSaveInitializeProvider，则会出现 E_GS_PROVIDER_MISMATCH 错误。 同样，如果游戏使用的是 XGameSave，并在以后调用 XGameSaveFilesGetFolderWithUiAsync，则也会出现 E_GS_PROVIDER_MISMATCH 错误。
要求
头文件：XGameSave.h
库：xgameruntime.lib
支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机