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

# 如何使用 Xbox 服務 API

> 初始化 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` 和不同的分派模式，請參閱[非同步工作佇列設計](https://docs.xbox.com/zh-TW/build/core-features/common/async/async-task-queue-design.md)。

例如，下列程式碼會使用系統執行緒集區建立工作佇列。

```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](https://docs.xbox.com/zh-TW/reference/system/xtaskqueue/functions/xtaskqueuesetcurrentprocesstaskqueue.md) 來覆寫此設定。

## 設定 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 網路

大多數 XSAPI 都要求使用者先登入 XBOX 網路。
若要將使用者登入 XBOX 網路，請參閱 [XUserAddAsync API](https://docs.xbox.com/zh-TW/build/core-features/common/user/xuser_howto_best_practice_signing_in.md) 的程式碼範例。

## 建立 XboxLiveContext 物件

`XboxLiveContext` 物件代表與特定使用者相關聯的服務內容。

大多數 XSAPI 都要求您傳入代表呼叫使用者內容的 `XboxLiveContextHandle`。
若要建立 XBOX Live (網路) 內容，請使用 [XblContextCreateHandle API](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle.md)，並傳入從上一個步驟取得的 `XUserHandle` 物件。

## 對 XBOX 服務進行服務呼叫

現在您已擁有與已登入使用者之 `XUserHandle` 物件相關聯的 `XboxLiveContext` 物件，就可以對 XBOX 服務進行服務呼叫。

例如，若要擷取使用者的好友清單，您可以執行下列動作：

```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。基於其生命週期的本質，應用程式終止需要同步且立即處理。因此，會依賴應用程式處理序終止時發生的一般作業系統層級清除，這對此情況而言已足夠。

在應用程式暫停的案例中，XSAPI 會處理釋放並還原運作所需的系統資源，以在繼續後維持功能。

在您的遊戲選擇刻意釋放配置給 XSAPI 之資源的情況下，仍可使用 `XblCleanupAsync()`。


## Related topics

- [XBOX 服務 API](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/xbox-services-api/index.md)
- [如何使用 XBOX PC 遠端工具](https://docs.xbox.com/zh-TW/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)
- [伺服器](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/servers/index.md)
- [使用 Fiddler 檢查 Web 服務呼叫](https://docs.xbox.com/zh-TW/tools/tools-services/live-fiddler-inspect-web-calls.md)
- [進階 XBOX 服務沙箱](https://docs.xbox.com/zh-TW/services/xbox-services/fundamentals/sandboxes/live-advanced-sandboxes.md)