XGameSaveInitializeProviderAsync

异步提供并初始化 XGameSave 提供程序句柄。

语法

HRESULT XGameSaveInitializeProviderAsync(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XAsyncBlock* async  
)  

参数

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 的句柄。

在 syncOnDemand 设置为 true 的情况下调用此 API 时，从调用方角度来说其行为完全相同，但它会导致其余 API 中的一些行为差异。 SyncOnDemandXGameSaveProvider 将仅在需要时从服务下载数据，但这同时也会带来某些缺点，就是在此情况下任何容器操作可能会延迟，并且此延迟可能导致某些 UX 显示给用户用于同步进度。 使用下列任何方法都可以强制同步：

• XGameSaveCreateUpdate
• XGameSaveEnumeratorBlobInfo
• XGameSaveEnumerateBlobInfoByName
• XGameSaveEnumerateContainerInfo
• XGameSaveEnumerateContainerInfoByName

另一个缺点是，如果设备脱机或存在连接问题，则无法访问改容器。

##示例

// ASYNC Init - can be kicked off from a time sensitive thread 
//              work and callback will happen from platform provided threads 
void Sample::_InitializeAsync() 
{ 
    HRESULT hr; 
  
    struct InitContext 
    { 
        Sample* self; 
        XAsyncBlock async; 
    }; 
  
    InitContext* ctx = new InitContext{}; 
    if (ctx) 
    { 
        ctx->self = this; 
        ctx->async.context = ctx; 
        ctx->async.callback = [](XAsyncBlock* async) 
        { 
            auto ctx = reinterpret_cast<InitContext*>(async->context); 
            auto self = ctx->self; 
            XGameSaveProviderHandle provider = nullptr; 
            HRESULT hr = XGameSaveInitializeProviderResult(async, &provider); 
            if (SUCCEEDED(hr)) 
            { 
                self->_provider = provider; 
            } 
            else 
            { 
                self->_HandleInitializeErrors(self->_xalUser, hr); 
            } 
            delete ctx; 
        }; 
    } 
    else 
    { 
        hr = E_OUTOFMEMORY; 
    } 
  
    if (SUCCEEDED(hr)) 
    { 
        hr = XGameSaveInitializeProviderAsync(this->_xalUser, "SERVICE_CONFIG_ID-DEADBEEF0123", false, &ctx->async); 
    } 
    if (FAILED(hr)) 
    { 
        // if we didn't setup the async we need to cleanup our tracking context 
        delete ctx; 
        _HandleInitializeErrors(this->_xalUser, hr); 
    } 
} 

游戏不能将 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
游戏保存错误