> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameSaveInitializeProviderAsync

> XGameSaveInitializeProviderAsync

# XGameSaveInitializeProviderAsync

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

## 语法

```cpp theme={null}
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\*](/reference/system/xasync/structs/xasyncblock)

包含异步调用的信息。这包括调用上下文以及对
[XGameSaveInitializeProviderResult](/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult) 函数的调用。

### 返回值

类型：HRESULT

函数结果。

## 备注

在使用其他 XGameSave API 之前必须成功调用此函数。

<Note>XGameSave API 要求你的游戏正确配置其游戏 ID 和服务配置 ID (SCID)</Note>
才能正常工作。有关这些必需 ID 的详细信息，请参阅[为 XBOX
Live 开发设置沙盒](/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes)。你的游戏必须在合作伙伴中心为 XBOX Live 启用。

如果你没有正确配置 SCID 和游戏 ID，则你的 XSaveGame API 调用将失败并返回以下错误代码：

E\_GS\_NO\_ACCESS - 0x80830002 - 由于游戏无权访问容器存储空间，因此操作失败。

得到的 **XGameSaveProviderHandle** 是从
[XGameSaveInitializeProviderResult](/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult) 函数获取的。你将使用此句柄来
访问你的 **XGameSaveProvider**。

当在调用此 API 时将 *syncOnDemand* 设置为 true 时，从调用方的角度看它的行为相同，但会导致 API 的其余部分出现
某些行为差异。*SyncOnDemand* **XGameSaveProvider** 仅在需要时从服务下载数据，但这也会带来一些缺点，即在这种情况下任何容器操作可能会延迟，
并且此延迟可能导致向用户显示某些 UX 以指示同步进度。使用以下任一方法都可以
强制同步：

* [XGameSaveCreateUpdate](/reference/system/xgamesave/functions/xgamesavecreateupdate)
* [XGameSaveEnumeratorBlobInfo](/reference/system/xgamesave/functions/xgamesaveenumerateblobinfo)
* [XGameSaveEnumerateBlobInfoByName](/reference/system/xgamesave/functions/xgamesaveenumerateblobinfobyname)
* [XGameSaveEnumerateContainerInfo](/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfo)
* [XGameSaveEnumerateContainerInfoByName](/reference/system/xgamesave/functions/xgamesaveenumeratecontainerinfobyname)

另一个缺点是，如果设备处于离线状态或存在连接问题，则无法访问容器。

\##示例

```cpp theme={null}
// 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 主机

## 概念性文档

* [异步编程设计目标和改进](/build/core-features/common/async/async-whitepaper)
* [游戏保存工具](/build/core-features/common/game-save/game-saves-tools)

## 另请参阅

[XGameSave](/reference/system/xgamesave/xgamesave_members)\
[XGameSaveInitializeProviderResult](/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult)\
[XGameSaveInitializeProvider](/reference/system/xgamesave/functions/xgamesaveinitializeprovider)\
[调试游戏保存](/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveInitializeProvider](/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md)
- [XGameSaveInitializeProviderResult](/zh-CN/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult.md)
- [XGameSaveCloseProvider](/zh-CN/reference/system/xgamesave/functions/xgamesavecloseprovider.md)
- [游戏存档工具](/zh-CN/build/core-features/common/game-save/game-saves-tools.md)
- [XGameSave](/zh-CN/reference/system/xgamesave/xgamesave_members.md)