> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling a social relationship change

> XSAPI code for handling XBOX services social relationship change events and adding or removing handlers when a user's friends list is updated.

This topic provides example code for handling a social relationship change. In the examples, `xboxLiveContext` is the `XblContextHandle` for the signed-in user, `state` holds your title's state, and `LogToFile` is a logging function that your title defines.

## Subscribing to relationship changes

You don't need to subscribe to relationship changes separately. The XBOX Services API (XSAPI) creates or reuses one social Real-Time Activity (RTA) subscription for the context. Relationship-changed handlers and incoming friend request count handlers share it. XSAPI removes the subscription only after you remove all handlers of both types.

> [!NOTE]
>
> `XblSocialSubscribeToSocialRelationshipChange` and `XblSocialUnsubscribeFromSocialRelationshipChange` are deprecated and don't manage the RTA subscription. Remove calls to them from your code as a pair. If your code already created a subscription handle with `XblSocialSubscribeToSocialRelationshipChange`, release it by calling `XblSocialUnsubscribeFromSocialRelationshipChange`.

## Adding a relationship-changed handler

**Flat C API**

```cpp theme={null}
state.socialRelationshipChangedHandlerToken = XblSocialAddSocialRelationshipChangedHandler(
    xboxLiveContext,
    [](const XblSocialRelationshipChangeEventArgs* args, void* context)
    {
        UNREFERENCED_PARAMETER(context);
        LogToFile("Social relationship changed:");
        std::stringstream ss;
        for (size_t i = 0; i < args->xboxUserIdsCount; ++i)
        {
            if (i > 0) 
            {
                ss << ", ";
            }
            ss << args->xboxUserIds[i];
        }
        LogToFile("socialNotification = %u, affectedXuids = %s", args->socialNotification, ss.str().data());
    },
    nullptr
);
```

## Removing a relationship-changed handler

**Flat C API**

```cpp theme={null}
HRESULT hr = XblSocialRemoveSocialRelationshipChangedHandler(xboxLiveContext, state.socialRelationshipChangedHandlerToken);
state.socialRelationshipChangedHandlerToken = 0;
```

## Handling a change in the number of incoming friend requests

**Flat C API**

```cpp theme={null}
XblFunctionContext friendRequestCountToken{ 0 };
HRESULT hr = XblSocialAddFriendRequestCountChangedHandler(
    xboxLiveContext,
    [](const XblSocialFriendRequestCountChangedEventArgs* args, void* context)
    {
        UNREFERENCED_PARAMETER(context);
        // args is valid only during the callback.
        LogToFile("Incoming friend requests: %zu", args->incomingFriendRequestCount);
    },
    nullptr,
    &friendRequestCountToken
);

if (SUCCEEDED(hr))
{
    // Keep the token until you no longer need notifications.
    state.friendRequestCountToken = friendRequestCountToken;
}
```

When you no longer need notifications, remove the handler. Remove only a handler that was registered successfully.

```cpp theme={null}
if (state.friendRequestCountToken != 0)
{
    HRESULT hr = XblSocialRemoveFriendRequestCountChangedHandler(xboxLiveContext, state.friendRequestCountToken);
    if (SUCCEEDED(hr))
    {
        state.friendRequestCountToken = 0;
    }
}
```

## See also

[XblSocialAddSocialRelationshipChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialaddsocialrelationshipchangedhandler.md)
[XblSocialRemoveSocialRelationshipChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialremovesocialrelationshipchangedhandler.md)
[XblSocialAddFriendRequestCountChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialaddfriendrequestcountchangedhandler.md)
[XblSocialRemoveFriendRequestCountChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialremovefriendrequestcountchangedhandler.md)


## Related topics

- [People System (Friends List) example code (contents)](https://docs.xbox.com/services/xbox-services/community/people-system/how-to/live-pplsys-howto-nav.md)
- [How to](https://docs.xbox.com/services/xbox-services/community/people-system/how-to/index.md)
- [XblSocialRelationshipChangeEventArgs](https://docs.xbox.com/reference/live/xsapi-c/social_c/structs/xblsocialrelationshipchangeeventargs.md)
- [XblSocialAddSocialRelationshipChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialaddsocialrelationshipchangedhandler.md)
- [XblSocialRemoveSocialRelationshipChangedHandler](https://docs.xbox.com/reference/live/xsapi-c/social_c/functions/xblsocialremovesocialrelationshipchangedhandler.md)