XGameSaveInitializeProvider

  • [アーティクル]

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

構文

HRESULT XGameSaveInitializeProvider(  
         XUserHandle requestingUser,  
         const char* configurationId,  
         bool syncOnDemand,  
         XGameSaveProviderHandle* provider  
)

パラメーター

requestingUser _In_
型: XUserHandle

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

configurationId _In_z_
型: char*

サービス構成 ID (SCID)。

syncOnDemand _In_
型: bool

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

provider _Outptr_result_nullonfailure_
型: XGameSaveProviderHandle*

作成する XGameSave プロバイダーに対するハンドル。

戻り値

型: HRESULT

関数の結果です。

一般的なエラー

  • E_GS_USER_CANCELED
  • E_GS_USER_NOT_REGISTERED_IN_SERVICE
  • E_GS_NO_ACCESS
  • E_GS_NO_SERVICE_CONFIGURATION

返されるエラーで最も一般的なものは、E_OUTOFMEMORY と E_INVALIDARG です。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。 詳細については、「時間依存のスレッド」を参照してください。

他の XGameSave API を使用する前に、この関数の呼び出しが成功する必要があります。 この関数は、プレイヤーのセーブ データを同期するときにブロックされてユーザーに UI を表示する可能性があるため、ゲームの UI スレッドで呼び出さないでください。 これを UI スレッドから初期化する必要がある場合は、XGameSaveInitializeProviderAsync の呼び出しを検討してください。

注意

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

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

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

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

もう 1 つの欠点は、デバイスがオフラインの場合、または接続に問題がある場合は、コンテナーにアクセスできません。 この関数には、XGameSaveInitializeProviderAsync という名前の非同期バージョンがあります

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

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

要件

ヘッダー: XGameSave.h

ライブラリ: xgameruntime.lib

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

関連項目

XGameSave
XGameSaveInitializeProviderAsync
ゲームのセーブ エラー