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 がユーザーに表示されるという欠点もあります。 次のいずれかの方法を使用すると、同期を強制できます。
- XGameSaveCreateUpdate
- XGameSaveEnumeratorBlobInfo
- XGameSaveEnumerateBlobInfoByName
- XGameSaveEnumerateContainerInfo
- XGameSaveEnumerateContainerInfoByName
もう 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 本体