> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX Services API (XSAPI) の使用方法

> GRTS を初期化し、XTaskQueue を作成し、HttpClient トレースをセットアップし、XblInitialize を呼び出して、タイトルで XBOX Live 用の XSAPI C API の使用を開始します。

## Gaming Runtime Services の初期化

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

```cpp theme={null}
#include <XGameRuntimeInit.h>
...
HRESULT hr = XGameRuntimeInitialize();
```

## XTaskQueue の作成 (オプション)

ほとんどの XSAPI は非同期 API であり、タスクキューの使用が必要です。これは、作業をキューに入れ、完了タスクのコールバックのための API です。`XTaskQueue` とさまざまなディスパッチモードの詳細については、[非同期タスクキューの設計](/build/core-features/common/async/async-task-queue-design) を参照してください。

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

```cpp theme={null}
#include <XTaskQueue.h>
...
XTaskQueueHandle queue = nullptr;

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

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

```cpp theme={null}
XTaskQueueCloseHandle(queue);
queue = nullptr;
```

独自のタスクキューを作成しない場合は、キューハンドルが必要なときに `nullptr` を渡してください。`nullptr` が使用されると、タスクシステムはデフォルトで `ThreadPool` を使用します。これは [XTaskQueueSetCurrentProcessTaskQueue](/reference/system/xtaskqueue/functions/xtaskqueuesetcurrentprocesstaskqueue) を呼び出してオーバーライドできます。

## HttpClient トレースのセットアップ (オプション)

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

次のコードは、`HttpClient` トレースレベルを設定し、デバッガ情報の出力を有効にします。

```cpp theme={null}
HCSettingsSetTraceLevel(HCTraceLevel::Verbose);
HCTraceSetTraceToDebugger(true);
```

## XSAPI の初期化

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

```cpp theme={null}
#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 network にサインインさせる

ほとんどの XSAPI では、ユーザーがまず XBOX network (XBOX Live とも呼ばれる) にサインインする必要があります。
ユーザーを XBOX network にサインインさせる方法については、[XUserAddAsync API](/build/core-features/common/user/xuser_howto_best_practice_signing_in) のコード例を参照してください。

## XboxLiveContext オブジェクトの作成

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

ほとんどの XSAPI は、呼び出し元のユーザーのコンテキストを表す `XboxLiveContextHandle` を渡す必要があります。
XBOX Live (network) コンテキストを作成するには、[XblContextCreateHandle API](/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle) を使用し、前のステップで取得した `XUserHandle` オブジェクトを渡します。

## XBOX services へのサービス呼び出しの実行

サインインしたユーザーの `XUserHandle` オブジェクトに関連付けられた `XboxLiveContext` オブジェクトが得られたので、XBOX services へのサービス呼び出しを実行できます。

例えば、ユーザーのフレンドリストを取得するには、次のようにします:

```cpp theme={null}
#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 に割り当てられたリソースを解放することを選択する場合に依然として使用できます。