Xbox サービス API (XSAPI) の使用を開始する

  • [アーティクル]

ゲーム ランタイム サービスを初期化します。

XSAPI は Gaming Runtime Services (GRTS) に依存します。 任意の XSAPI を呼び出す前に、次のように GRTS を初期化します。

#include <XGameRuntimeInit.h>
...
HRESULT hr = XGameRuntimeInitialize();

XTaskQueue の作成 (オプション)

ほとんどの XSAPI は非同期 API であり、タスク キューを使用する必要があります。 これは、作業をキューに入れ、完了タスクのコールバックを行う API です。 XTaskQueue のさまざまなディスパッチ モードの詳細については、「Async タスク キューの設計」を参照してください。

たとえば、次のコードでは、システムのスレッド プールを使用してタスク キューを作成します。

#include <XTaskQueue.h>
...
XTaskQueueHandle queue = nullptr;

HRESULT hr = XTaskQueueCreate(
    XTaskQueueDispatchMode::ThreadPool,
    XTaskQueueDispatchMode::ThreadPool,
    &queue)

取得したタスク キュー ハンドルが不要になったら、必ずシステムに戻してください。

XTaskQueueCloseHandle(queue);
queue = nullptr;

独自のタスク キューを作成しない場合は、キュー ハンドルが必要なときに必ず nullptr を渡してください。 nullptr が使用されている場合、タスク システムは既定で ThreadPool を使用します。 これは、XTaskQueueSetCurrentProcessTaskQueue を呼び出すことによってオーバーライドできます。

HttpClient トレースを設定する (オプション)

追加のランタイム デバッグ情報を表示するには、必ず HttpClient のトレース機能を設定してください。

次のコードでは、HttpClient トレース レベルが設定されて、デバッガ情報の出力が有効になります。

HCSettingsSetTraceLevel(HCTraceLevel::Verbose);
HCTraceSetTraceToDebugger(true);

XSAPI を初期化する

XSAPI を呼び出す前に XSAPI を初期化します。

#include <xsapi-c/services-c.h>
...
XblInitArgs xblArgs = {};
xblArgs.queue = queue; // TODO: Only include this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line isn't needed.
xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // TODO: Add your scid here.

HRESULT hr = XblInitialize(&xblArgs);
if (FAILED(hr))
{
    // TODO: Handle failure.
}

Xbox ネットワークにユーザーをサインインする

ほとんどの XSAPI では、ユーザーが最初に Xbox ネットワーク (Xbox Live とも呼ばれる) にサインインする必要があります。
Xbox ネットワークにユーザーをサインインするには、XUserAddAsync API のコード例を参照してください。

XboxLiveContext オブジェクトを作成する

XboxLiveContext オブジェクトは、特定のユーザーに関連付けられているサービス コンテキストを表します。

ほとんどの XSAPI では、呼び出し元のユーザーのコンテキストを表す XboxLiveContextHandle を渡す必要があります。
Xbox Live (ネットワーク) コンテキストを作成するには、XblContextCreateHandle API を使用し、前の手順で取得した XUserHandle オブジェクトを渡します。

Xbox サービス にサービスの呼び出しを発信する

これで、サインインしたユーザーの XUserHandle オブジェクトに関連付けられた XboxLiveContext オブジェクトが作成されたため、Xbox サービスへのサービス呼び出しを行うことができます。

たとえば、ユーザーのフレンド リストを取得するには、次の操作を行います。

#include <xsapi-c/services-c.h>
...
auto asyncBlock = std::make_unique<XAsyncBlock>(); 
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblSocialRelationshipResultHandle relationshipResult{ nullptr };
    HRESULT hr = XblSocialGetSocialRelationshipsResult(asyncBlock, &state.socialResultHandle);

    // Use the result in the game.

    XblSocialRelationshipResultCloseHandle(relationshipResult);
};

HRESULT hr = XblSocialGetSocialRelationshipsAsync(
    xboxLiveContext,
    xboxUserId,
    socialRelationshipFilter,
    0,
    0,
    asyncBlock.get()
);

if (SUCCEEDED(hr))
{
    // The call succeeded. Release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, the std::unique_ptr will keep ownership and delete the XAsyncBlock*.
    asyncBlock.release();
}
// End of code example.

XSAPI をクリーンアップする

どのようなシナリオでも XblCleanupAsync() を呼び出す必要はありません。

アプリ終了シナリオでは、現在、呼び出すことができる同期 XblCleanup() API はありません。 ライフサイクルの性質上、アプリの終了は同期的かつ即時に処理する必要があります。 その結果、アプリのプロセス終了によって発生する通常の OS レベルのクリーンアップは、この状況に依存している十分な処理です。

アプリが中断されるシナリオでは、再開後に機能を維持するために、XSAPI は操作に必要なシステム リソースの解放と復元を処理します。

XblCleanupAsync() は、ゲームが XSAPI に割り当てられたリソースを意図的に解放することを選択した場合でも使用できます。