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

Provides and initializes a XGameSave Provider handle.

## Syntax

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

### Parameters

*requestingUser*   \_In\_\
Type: XUserHandle

Handle to an XBOX Live user.

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

Service configuration ID (SCID).

*syncOnDemand*   \_In\_\
Type: bool

When true, syncOnDemand only downloads data from the service if needed. Does not work if device is offline.
Setting to true may cause sync progress UI to be shown.

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

A handle to the XGameSave Provider to be created.

### Return value

Type: HRESULT

Function result.

#### Common errors

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

The most commonly returned errors are E\_OUTOFMEMORY, E\_INVALIDARG,

## Remarks

<Note>This function isn't safe to call on a time-sensitive thread. For more information, see [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

This function must be called successfully before other XGameSave APIs are used. This function should not
be called on the game's UI thread as it can block and potentially show UI to the user as it synchronizes
the player's game saves. If you need to initialize this from the UI thread, consider calling
[XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync).

<Note>The XGameSave API requires your title to have its title ID and service configuration ID (SCID)</Note>
properly configured in order to work. For more information about these required IDs, see [Setting Up Sandboxes for XBOX
Live Development](/services/xbox-services/fundamentals/sandboxes/live-setting-up-sandboxes). Your game must be enabled for XBOX Live in Partner Center.

If you do not configure your SCID and Title ID properly, your XSaveGame API calls will fail with the following error code:

E\_GS\_NO\_ACCESS - 0x80830002 - The operation failed because the title does not have access to the container storage spaces.

When this API is called with *syncOnDemand* set to true it behaves the same from a caller perspective but it does cause
some behavior differences in the rest of the API. The *SyncOnDemand* **XGameSaveProvider** will only download data from
the service if needed but this also comes with the drawback that any container operation might be delayed in this case
and this delay may cause some UX to be shown to the user for the sync progress. Using any of the following methods can
force a sync:

* [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)

Another drawback would be that if the device is offline or has connectivity issues then accessing the container is
impossible. There is an asynchronous version of this function called
[XGameSaveInitializeProviderAsync](/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); 
    } 
} 
```

Games cannot mix the usage of XGameSaveFiles with the usage of XGameSave. Games much choose which cloud save system
they want to use. If the game is using XGameSaveFiles and later calls XGameSaveInitializeProvider, it will error out
with E\_GS\_PROVIDER\_MISMATCH. Equally, if the game was using XGameSave and later calls XGameSaveFilesGetFolderWithUiAsync,
that will also error out with E\_GS\_PROVIDER\_MISMATCH.

## Requirements

**Header:** XGameSave.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [Game Saves tools](/build/core-features/common/game-save/game-saves-tools)
* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XGameSave](/reference/system/xgamesave/xgamesave_members)\
[XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync)\
[Debugging Game Saves](/build/core-features/common/game-save/game-saves-debugging)


## Related topics

- [XGameSaveInitializeProviderAsync](/reference/system/xgamesave/functions/xgamesaveinitializeproviderasync.md)
- [XGameSaveCloseProvider](/reference/system/xgamesave/functions/xgamesavecloseprovider.md)
- [Game Saves tools](/build/core-features/common/game-save/game-saves-tools.md)
- [Game Saves walkthroughs and samples](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md)
- [XGameSave API overview](/build/core-features/common/game-save/xgamesave.md)