Handling a title Presence change

This article provides example code that uses the XBOX services API (XSAPI) to handle title Presence changes. To receive title Presence notifications, register a handler first, and then track the users and titles that you’re interested in. When you no longer need notifications, stop tracking the users and titles and remove the handler. In the examples, xboxLiveContext is an XblContextHandle for the signed-in local user, state is a title-defined object that stores the handler token, and LogToFile is a title-defined logging function. Replace 123 with the XBOX user ID (XUID) of a user whose Presence you want to track, and replace otherTitleId with the title ID of another title that you want to track.

XblPresenceSubscribeToTitlePresenceChange and XblPresenceUnsubscribeFromTitlePresenceChange are deprecated. Don’t use them in new code. XSAPI manages the Real-Time Activity (RTA) subscriptions for you when you track users with XblPresenceTrackUsers and titles with XblPresenceTrackAdditionalTitles.

Adding a title Presence change handler

Register the handler before you track users and titles. The function returns 0 if xblContextHandle or handler is null.

state.titlePresenceChangedHandlerToken = XblPresenceAddTitlePresenceChangedHandler(
    xboxLiveContext,
    [](void* context, uint64_t xuid, uint32_t titleId, XblPresenceTitleState titleState)
    {
        UNREFERENCED_PARAMETER(context);
        LogToFile("Title presence change notification received:");
        LogToFile("Xuid = %llu, titleId = %u, titleState = %u",
            static_cast<unsigned long long>(xuid),
            titleId,
            static_cast<uint32_t>(titleState));
    },
    nullptr
);

if (state.titlePresenceChangedHandlerToken == 0)
{
    // The handler wasn't registered.
}

For more information, see XblPresenceTitleState.

Tracking users and titles

Title Presence change handlers receive notifications only for the users that you track with XblPresenceTrackUsers and the titles that you track. The current title is tracked by default, so call XblPresenceTrackAdditionalTitles only for other titles. Each call adds to the existing list. Check the result of each call.

uint64_t xuids[]{ 123 };
uint32_t titleIds[]{ otherTitleId };

HRESULT hr = XblPresenceTrackUsers(
    xboxLiveContext,
    xuids,
    _countof(xuids)
);

if (SUCCEEDED(hr))
{
    hr = XblPresenceTrackAdditionalTitles(
        xboxLiveContext,
        titleIds,
        _countof(titleIds)
    );
}

Tracking is reference counted. Make a matching stop call for each successful tracking call. The list of tracked users applies to both device and title Presence notifications.

Stopping tracking users and titles

When you no longer need title Presence updates, stop tracking the titles and users that you tracked, and check each result. XblPresenceStopTrackingAdditionalTitles doesn’t stop tracking the current title.

HRESULT hr = XblPresenceStopTrackingAdditionalTitles(
    xboxLiveContext,
    titleIds,
    _countof(titleIds)
);

HRESULT hrUsers = XblPresenceStopTrackingUsers(
    xboxLiveContext,
    xuids,
    _countof(xuids)
);

Removing a title Presence change handler

Remove the handler by passing the token that XblPresenceAddTitlePresenceChangedHandler returned. Clear the stored token only after the call succeeds.

HRESULT hr = XblPresenceRemoveTitlePresenceChangedHandler(
    xboxLiveContext,
    state.titlePresenceChangedHandlerToken
);

if (SUCCEEDED(hr))
{
    state.titlePresenceChangedHandlerToken = 0;
}

XBOX Services

PlayFab

Adding a title Presence change handler

Tracking users and titles

Stopping tracking users and titles

Removing a title Presence change handler

See also

​Adding a title Presence change handler

​Tracking users and titles

​Stopping tracking users and titles

​Removing a title Presence change handler

​See also

Adding a title Presence change handler

Tracking users and titles

Stopping tracking users and titles

Removing a title Presence change handler

See also