Skip to main content

XGameSaveInitializeProvider

Provides and initializes a XGameSave Provider handle.

Syntax

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

This function isn’t safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.
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.
The XGameSave API requires your title to have its title ID and service configuration ID (SCID)
properly configured in order to work. For more information about these required IDs, see Setting Up Sandboxes for XBOX Live Development. 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: 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
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

See also

XGameSave
XGameSaveInitializeProviderAsync
Debugging Game Saves
Last modified on August 20, 2026