XGameSaveInitializeProviderAsync

Provides and initializes an XGameSave Provider handle asynchronously.

Syntax

HRESULT XGameSaveInitializeProviderAsync(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XAsyncBlock* async  
)  

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.

async   _In_
Type: XAsyncBlock*

Contains the information for the Async call. This includes calling context and a call to the XGameSaveInitializeProviderResult function.

Return value

Type: HRESULT

Function result.

Remarks

This function must be called successfully before other XGameSave APIs are used.

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.

The resulting XGameSaveProviderHandle is obtained from the XGameSaveInitializeProviderResult function. This is the handle you will use to access your XGameSaveProvider.

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
• XGameSaveEnumeratorBlobInfo
• XGameSaveEnumerateBlobInfoByName
• XGameSaveEnumerateContainerInfo
• XGameSaveEnumerateContainerInfoByName

Another drawback would be that if the device is offline or has connectivity issues then accessing the container is impossible.

##Example

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

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

See also

XGameSave
XGameSaveInitializeProviderResult
XGameSaveInitializeProvider
Game save errors