> ## 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.

# How to use XBOX Services APIs (XSAPIs)

> Initialize GRTS, create an XTaskQueue, set up HttpClient tracing, and call XblInitialize to start using the XSAPI C APIs for XBOX Live in your title.

## Initialize Gaming Runtime Services

XSAPIs depend on Gaming Runtime Services (GRTS). Before calling any XSAPIs, initialize GRTS, shown as follows.

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

## Create XTaskQueue (optional)

Most of the XSAPIs are asynchronous APIs and require the use of a task queue. It's an API for queuing work and for completion task callbacks. To learn more about `XTaskQueue` and different dispatch modes, see [Async task queue design](/build/core-features/common/async/async-task-queue-design).

For example, the following code creates a task queue by using a system thread pool.

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

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

Ensure that you release your acquired task queue handle back to the system when it's no longer needed.

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

If you choose not to create your own task queue, ensure that you pass in `nullptr` when a queue handle is needed. When `nullptr` is used, the task system uses `ThreadPool` by default. It can be overridden by calling [XTaskQueueSetCurrentProcessTaskQueue](/reference/system/xtaskqueue/functions/xtaskqueuesetcurrentprocesstaskqueue).

## Set up HttpClient trace (optional)

To view additional runtime debug information, ensure that you set up the trace functionality of `HttpClient`.

The following code sets the `HttpClient` trace level and enables output for debugger information.

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

## Initialize XSAPI

*Initialize XSAPI* before calling any XSAPIs.

```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.
}
```

## Sign the user in to the XBOX network

Most of the XSAPIs require the user to first sign in to the XBOX network (also known as XBOX Live).
To sign a user in to the XBOX network, see the code example of the [XUserAddAsync API](/build/core-features/common/user/xuser_howto_best_practice_signing_in).

## Create an XboxLiveContext object

An `XboxLiveContext` object represents the service context that is associated to a particular user.

Most XSAPIs require you to pass in an `XboxLiveContextHandle` that represents the context of the calling user.
To create an XBOX Live (network) context, use the [XblContextCreateHandle API](/reference/live/xsapi-c/xbox_live_context_c/functions/xblcontextcreatehandle) and pass in the `XUserHandle` object that was acquired from the previous step.

## Make a service call to XBOX services

Now that you have an `XboxLiveContext` object associated with the `XUserHandle` object for the user who has signed in, you can make service calls to XBOX services.

For example, to retrieve the user's friends list, you can do the following:

```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.
```

## Cleaning up XSAPI

It is not necessary to call `XblCleanupAsync()` in any scenario.

In an app termination scenario, there is currently no synchronous `XblCleanup()` API that you can call. App termination, by its life-cycle nature, needs to be handled synchronously and immediately. As a result, normal OS-level cleanup - that happens with process termination of the app - is relied upon and is sufficient for this situation.

In a scenario where the app is suspended, XSAPI handles releasing and then restoring the system resources required for operation in order to maintain functionality after resume.

`XblCleanupAsync()` can still be used in cases where your game chooses to deliberately release the resources allocated to XSAPI.