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

# XGameSaveInitializeProvider

> XGameSaveInitializeProvider

# XGameSaveInitializeProvider

Fornece e inicializa um identificador de XGameSave Provider.

## Sintaxe

```cpp theme={null}
HRESULT XGameSaveInitializeProvider(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XGameSaveProviderHandle* provider  
)  
```

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

*provider*   \_Outptr\_result\_nullonfailure\_\
Tipo: XGameSaveProviderHandle\*

Um identificador para o XGameSave Provider a ser criado.

### Valor retornado

Tipo: HRESULT

Resultado da função.

#### Erros comuns

* E\_GS\_USER\_CANCELED
* E\_GS\_USER\_NOT\_REGISTERED\_IN\_SERVICE
* E\_GS\_NO\_ACCESS
* E\_GS\_NO\_SERVICE\_CONFIGURATION

Os erros retornados com mais frequência são E\_OUTOFMEMORY, E\_INVALIDARG,

## Comentários

<Note>Não é seguro chamar esta função em uma thread sensível ao tempo. Para obter mais informações, consulte [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

Esta função deve ser chamada com êxito antes que outras APIs XGameSave sejam usadas. Esta função não deve
ser chamada na thread de interface do usuário do jogo, pois ela pode bloquear e potencialmente mostrar a interface do usuário ao usuário enquanto sincroniza
os salvamentos de jogos do jogador. Se você precisar inicializá-la a partir da thread de interface do usuário, considere chamar
[XGameSaveInitializeProviderAsync](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync).

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

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. Há uma versão assíncrona desta função chamada
[XGameSaveInitializeProviderAsync](/pt-BR/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)

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

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

* [Ferramentas de salvamentos de jogos](/pt-BR/build/core-features/common/game-save/game-saves-tools)
* [Threads sensíveis ao tempo](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## Confira também

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


## Related topics

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