> ## 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

Fornece e inicializa de forma assíncrona um identificador de XGameSave Provider.

## Sintaxe

```cpp theme={null}
HRESULT XGameSaveInitializeProviderAsync(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XAsyncBlock* async  
)  
```

### Parâmetros

*requestingUser*   \_In\_\
Tipo: XUserHandle

Identificador para um usuário do XBOX Live.

*configurationId*   \_In\_z\_\
Tipo: char\*

ID de configuração de serviço (SCID).

*syncOnDemand*   \_In\_\
Tipo: bool

Quando true, syncOnDemand só baixa dados do serviço se necessário. Não funciona se o dispositivo estiver offline.
Defini-lo como true pode fazer com que a interface do usuário de progresso da sincronização seja mostrada.

*async*   \_In\_\
Tipo: [XAsyncBlock\*](/pt-BR/reference/system/xasync/structs/xasyncblock)

Contém as informações da chamada assíncrona. Isso inclui o contexto de chamada e uma chamada para a função
[XGameSaveInitializeProviderResult](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult).

### Valor retornado

Tipo: HRESULT

Resultado da função.

## Comentários

Esta função deve ser chamada com êxito antes que outras APIs XGameSave sejam usadas.

<Note>A API XGameSave exige que seu título tenha a ID do título e a ID de configuração de serviço (SCID)</Note>
configuradas corretamente para funcionar. Para obter mais informações sobre essas IDs obrigatórias, consulte [Configurando sandboxes para o desenvolvimento
no XBOX Live](/pt-BR/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes). Seu jogo deve estar habilitado para XBOX Live no Partner Center.

Se você não configurar a SCID e a ID do título corretamente, suas chamadas à API XSaveGame falharão com o seguinte código de erro:

E\_GS\_NO\_ACCESS - 0x80830002 - A operação falhou porque o título não tem acesso aos espaços de armazenamento do contêiner.

O **XGameSaveProviderHandle** resultante é obtido da função
[XGameSaveInitializeProviderResult](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult). Esse é o identificador que você usará para
acessar seu **XGameSaveProvider**.

Quando esta API é chamada com *syncOnDemand* definido como true, ela se comporta da mesma forma da perspectiva do chamador, mas causa
algumas diferenças de comportamento no restante da API. O **XGameSaveProvider** *SyncOnDemand* só baixará dados do
serviço se necessário, mas isso também tem a desvantagem de que qualquer operação de contêiner pode ser atrasada nesse caso
e esse atraso pode fazer com que alguma UX seja mostrada ao usuário para o progresso da sincronização. Usar qualquer um dos seguintes métodos pode
forçar uma sincronização:

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

Outra desvantagem é que, se o dispositivo estiver offline ou tiver problemas de conectividade, o acesso ao contêiner será
impossível.

\##Exemplo

```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); 
    } 
} 
```

Os jogos não podem misturar o uso de XGameSaveFiles com o uso de XGameSave. Os jogos devem escolher qual sistema de salvamento na nuvem
desejam usar. Se o jogo estiver usando XGameSaveFiles e depois chamar XGameSaveInitializeProvider, ocorrerá o erro
E\_GS\_PROVIDER\_MISMATCH. Da mesma forma, se o jogo estava usando XGameSave e depois chamar XGameSaveFilesGetFolderWithUiAsync,
também ocorrerá o erro E\_GS\_PROVIDER\_MISMATCH.

## Requisitos

**Cabeçalho:** XGameSave.h

**Biblioteca:** xgameruntime.lib

**Plataformas com suporte:** Windows, consoles da família XBOX One e consoles XBOX Series

## Documentação conceitual

* [Metas de design e melhorias da programação assíncrona](/pt-BR/build/core-features/common/async/async-whitepaper)
* [Ferramentas de salvamentos de jogos](/pt-BR/build/core-features/common/game-save/game-saves-tools)

## Confira também

[XGameSave](/pt-BR/reference/system/xgamesave/xgamesave_members)\
[XGameSaveInitializeProviderResult](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult)\
[XGameSaveInitializeProvider](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeprovider)\
[Depuração de salvamentos de jogos](/pt-BR/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md)
- [XGameSaveInitializeProviderResult](/reference/system/xgamesave/functions/xgamesaveinitializeproviderresult.md)
- [XGameSaveInitializeProvider](/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md)
- [XGameSaveCloseProvider](/reference/system/xgamesave/functions/xgamesavecloseprovider.md)