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

# XblRealTimeActivityAddConnectionStateChangeHandler

> Registers a handler that's called when the connection to the Real-Time Activity (RTA) service changes state.

Registers a handler function to receive a notification that is sent when the client service loses or gains connectivity to the Real-Time Activity (RTA) service.

## Syntax

```cpp theme={null}
XblFunctionContext XblRealTimeActivityAddConnectionStateChangeHandler(  
         XblContextHandle xboxLiveContext,  
         XblRealTimeActivityConnectionStateChangeHandler* handler,  
         void* context  
)  
```

### Parameters

*xboxLiveContext*   \_In\_\
Type: [XblContextHandle](https://docs.xbox.com/reference/live/xsapi-c/types_c/handles/xblcontexthandle.md)

XBOX services context handle.

*handler*   \_In\_\
Type: [XblRealTimeActivityConnectionStateChangeHandler\*](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/functions/xblrealtimeactivityconnectionstatechangehandler.md)

The callback function that receives notifications.

*context*   \_In\_opt\_\
Type: void\*

Caller context that will be passed back to the handler function.

### Return value

Type: XblFunctionContext

An XblFunctionContext object that can be used to unregister the event handler. Pass it to [XblRealTimeActivityRemoveConnectionStateChangeHandler](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/functions/xblrealtimeactivityremoveconnectionstatechangehandler.md).

A successful registration returns a token greater than 0. If the function fails, it can return an HRESULT error code cast to `XblFunctionContext`, which is a negative value. Possible error codes include the following. This list isn't exhaustive.

| Return code | Description |
| - | - |
| E\_INVALIDARG | *xboxLiveContext* or *handler* is null. |
| E\_XBL\_NOT\_INITIALIZED | The XBOX services API (XSAPI) isn't initialized. Call [XblInitialize](https://docs.xbox.com/reference/live/xsapi-c/xbox_live_global_c/functions/xblinitialize.md) first. |

## Remarks

The handler is registered for the user that's associated with *xboxLiveContext*. XSAPI also calls the handler with `XblRealTimeActivityConnectionState::Disconnected` when it closes an idle connection because the user has no remaining RTA subscriptions or legacy activations.

XSAPI catches and logs exceptions that the handler throws.

## Requirements

**Header:** real\_time\_activity\_c.h

**Library:** Microsoft.Xbox.Services.142.C.lib or Microsoft.Xbox.Services.143.C.lib

## See also

[real\_time\_activity\_c](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/real_time_activity_c_members.md)


## Related topics

- [XblRealTimeActivitySubscriptionErrorHandler](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/functions/xblrealtimeactivitysubscriptionerrorhandler.md)
- [real_time_activity_c (contents)](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/real_time_activity_c_members.md)
- [XblRealTimeActivityConnectionStateChangeHandler](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/functions/xblrealtimeactivityconnectionstatechangehandler.md)
- [XblRealTimeActivityRemoveConnectionStateChangeHandler](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/functions/xblrealtimeactivityremoveconnectionstatechangehandler.md)
- [XblRealTimeActivityConnectionState](https://docs.xbox.com/reference/live/xsapi-c/real_time_activity_c/enums/xblrealtimeactivityconnectionstate.md)