> ## 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 네트워크에 사용자 로그인

대부분의 XSAPI는 사용자가 먼저 XBOX 네트워크(XBOX Live라고도 함)에 로그인해야 합니다.
XBOX 네트워크에 사용자를 로그인하려면 [XUserAddAsync API](/build/core-features/common/user/xuser_howto_best_practice_signing_in)의 코드 예제를 참조하세요.

## XboxLiveContext 개체 생성

`XboxLiveContext` 개체는 특정 사용자와 연결된 서비스 컨텍스트를 나타냅니다.

대부분의 XSAPI는 호출하는 사용자의 컨텍스트를 나타내는 `XboxLiveContextHandle`을 전달해야 합니다.
XBOX Live(네트워크) 컨텍스트를 생성하려면 [XblContextCreateHandle API](/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle)를 사용하고 이전 단계에서 획득한 `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는 없습니다. 앱 종료는 그 수명 주기 특성상 동기적이고 즉각적으로 처리되어야 합니다. 결과적으로, 앱의 프로세스 종료와 함께 발생하는 일반적인 OS 수준 정리에 의존하며 이 상황에서는 이것으로 충분합니다.

앱이 일시 중단되는 시나리오에서는 XSAPI가 재개 후 기능을 유지하기 위해 작업에 필요한 시스템 리소스 해제 및 복원을 처리합니다.

`XblCleanupAsync()`는 게임이 XSAPI에 할당된 리소스를 의도적으로 해제하기로 선택하는 경우에 여전히 사용할 수 있습니다.


## Related topics

- [XBOX services API](/ko/services/xbox-services/fundamentals/xbox-services-api/index.md)
- [방법](/ko/services/xbox-services/community/presence/how-to/index.md)
- [방법 안내](/ko/services/xbox-services/multiplayer/invites/how-to/index.md)
- [XBOX services API 개요](/ko/services/xbox-services/fundamentals/xbox-services-api/live-introduction-to-xbox-live-apis.md)
- [XBOX Achievements Manager API 개요](/ko/services/xbox-services/player-data/achievements/achievements-manager/live-achievements-manager-overview.md)