XSAPI(Xbox 서비스 API) 시작하기

아티클
11/11/2023

게임 런타임 서비스 초기화

XSAPI는 GRTS(게임 런타임 서비스)에 의존합니다. XSAPI를 호출하기 전에 다음과 같이 GRTS를 초기화합니다.

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

XTaskQueue 생성(선택 사항)

대부분의 XSAPI는 비동기 API이며 작업 큐를 사용해야 합니다. 작업 대기 및 완료 작업 콜백을 위한 API입니다. XTaskQueue 및 다양한 디스패치 모드에 대해 자세히 알아보려면 비동기 작업 큐 디자인을 참조하세요.

예를 들어 다음 코드는 시스템 스레드 풀을 사용하여 작업 대기열을 만듭니다.

#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에 할당된 리소스를 의도적으로 해제하도록 선택하는 경우에도 계속 사용할 수 있습니다.

다음을 통해 공유