次の方法で共有

XGameSaveInitializeProviderAsync

  • [アーティクル]

非同期的に XGameSave プロバイダー ハンドルを提供して初期化します。

構文

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

パラメーター

requestingUser _In_
型: XUserHandle

Xbox Live ユーザーに対するハンドル。

configurationId _In_z_
型: char*

サービス構成 ID (SCID)。

syncOnDemand _In_
型: bool

true の場合、syncOnDemand は必要に応じてサービスからのデータのダウンロードのみを行います。 デバイスがオフラインの場合は動作しません。 true に設定すると、同期進行状況 UI が表示される場合があります。

async _In_
型: XAsyncBlock*

非同期呼び出しの情報が格納されます。 これには、呼び出しのコンテキストと、XGameSaveInitializeProviderResult 関数の呼び出しが含まれます。

戻り値

型: HRESULT

関数の結果です。

解説

他の XGameSave API を使用する前に、この関数の呼び出しが成功する必要があります。

注意

XGameSave API が動作するためには、タイトルでタイトル ID とサービス コンフィグ ID (SCID) が適切に構成されていることが必要です。 これらの必須 ID の詳細については、「Xbox Live 開発のためのサンドボックスのセットアップ」をご覧ください。 パートナー センターでゲームを Xbox Live 向けに有効にする必要があります。

SCID とタイトル ID が正しく構成されていない場合は、XSaveGame API を呼び出したときに次のエラー コードが返されます。

E_GS_NO_ACCESS - 0x80830002 - 操作は、タイトルがコンテナー ストレージ領域へのアクセス権を持っていないために失敗しました。

結果の XGameSaveProviderHandle は、XGameSaveInitializeProviderResult 関数から取得します。 これは、XGameSaveProvider へのアクセスに使用するハンドルです。

syncOnDemand を true に設定してこの API を呼び出すと、呼び出し元から見た動作は同じですが、API の他の部分については動作が違なります。 SyncOnDemandXGameSaveProvider は、必要に応じてサービスからデータをダウンロードするだけですが、この場合はコンテナー操作が遅延する可能性があり、この遅延によって同期の進行状況のために一部の UX がユーザーに表示されるという欠点もあります。 次のいずれかの方法を使用すると、同期を強制できます。

もう 1 つの欠点は、デバイスがオフラインの場合、または接続に問題がある場合は、コンテナーにアクセスできません。

##例

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

ゲームでは、XGameSaveFiles の使用法と XGameSave の使用法を混在させることはできません。 ゲームは、使用するクラウド保存システムを選択します。 ゲームが XGameSaveFiles を使用しており、後で XGameSaveInitializeProvider を呼び出すと、E_GS_PROVIDER_MISMATCH でエラーが発生します。 同様に、ゲームが XGameSave を使用しており、後で XGameSaveFilesGetFolderWithUiAsync を呼び出すと、これも E_GS_PROVIDER_MISMATCH でエラーが発生します。

要件

ヘッダー: XGameSave.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

関連項目

XGameSave
XGameSaveInitializeProviderResult
XGameSaveInitializeProvider
ゲームのセーブ エラー