Handling a device Presence change

This article provides example code that uses the XBOX services API (XSAPI) to handle device Presence changes. To receive device Presence notifications, register a handler and track the users that you’re interested in. When you no longer need notifications, stop tracking the users 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.

XblPresenceSubscribeToDevicePresenceChange and XblPresenceUnsubscribeFromDevicePresenceChange 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 stop tracking them with XblPresenceStopTrackingUsers.

Adding a device Presence change handler

Register a handler that XSAPI calls when the device Presence of a tracked user changes. The function returns 0 if xblContextHandle or handler is null.

state.devicePresenceChangedHandlerToken = XblPresenceAddDevicePresenceChangedHandler(
    xboxLiveContext,
    [](void* context, uint64_t xuid, XblPresenceDeviceType deviceType, bool isUserLoggedOnDevice)
    {
        UNREFERENCED_PARAMETER(context);
        LogToFile("Device presence change notification received:");
        LogToFile("Xuid = %llu, deviceType = %u, isUserLoggedOnDevice = %u",
            static_cast<unsigned long long>(xuid),
            static_cast<uint32_t>(deviceType),
            static_cast<uint32_t>(isUserLoggedOnDevice));
    },
    nullptr
);

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

For more information, see XblPresenceDeviceType.

Tracking users for device Presence changes

Device Presence change handlers receive notifications only for the users that you track with XblPresenceTrackUsers. Each call adds users to the existing list of tracked users. You can update the list of tracked users independently from the handlers.

uint64_t xuids[]{ 123 };

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

Tracking is reference counted. If you track the same user more than once, make a matching XblPresenceStopTrackingUsers call for each successful XblPresenceTrackUsers call. The list of tracked users applies to both device and title Presence notifications.

Stopping tracking users

When you no longer need Presence updates for a user, stop tracking the user.

uint64_t xuids[]{ 123 };

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

Removing a device Presence change handler

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

HRESULT hr = XblPresenceRemoveDevicePresenceChangedHandler(
    xboxLiveContext,
    state.devicePresenceChangedHandlerToken
);

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

XBOX Services

PlayFab

Adding a device Presence change handler

Tracking users for device Presence changes

Stopping tracking users

Removing a device Presence change handler

See also

​Adding a device Presence change handler

​Tracking users for device Presence changes

​Stopping tracking users

​Removing a device Presence change handler

​See also

Adding a device Presence change handler

Tracking users for device Presence changes

Stopping tracking users

Removing a device Presence change handler

See also