Channel subscriptions

By default a user only sees other clients that are in the same channel. Clients joining or leaving other channels or changing status are not displayed or announced to a client. To offer a way to get notifications about clients in other channels, a user can subscribe to other channels. It is also possible to always subscribe to all channels to get notifications about all clients on the server.

Subscriptions are meant to have a flexible way to balance bandwidth usage. On a crowded server limiting the number of subscribed channels is a way to reduce network traffic.

In addition subscriptions allow to have “private” channels, in that other clients cannot see who is in a channel.

Note

A client is always automatically subscribed to the current channel.

Subscribe to channels

To subscribe to a list of channels call

unsigned int ts3client_requestChannelSubscribe(uint64 serverConnectionHandlerID, const uint64 *channelIDArray, const char *returnCode)

Request live updates to specific channels, being able to see clients in the channel.

If you intend to subscribe to all channels on the server, use ts3client_requestChannelSubscribeAll function instead. You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

• serverConnectionHandlerID – the connection handler on which to subscribe to the specified channels

• channelIDArray – a zero terminated array of channel ids to subscribe to

• returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

To subscribe to all the channels on the server call

unsigned int ts3client_requestChannelSubscribeAll(uint64 serverConnectionHandlerID, const char *returnCode)

Request live updates from all channels, being able to see clients in the channels.

If you only want to subscribe to a specific subset of channels, use ts3client_requestChannelSubscribe funtion instead. You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

• serverConnectionHandlerID – the connection handler on which to subscribe to all channels

• returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Unsubscribe from channels

To unsubscribe from a list of channels call

unsigned int ts3client_requestChannelUnsubscribe(uint64 serverConnectionHandlerID, const uint64 *channelIDArray, const char *returnCode)

Remove subscription from channels. No longer receiving updates to clients in the channels.

You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

• serverConnectionHandlerID – the connection handler on which to unsubscribe from the specified channels

• channelIDArray – a zero terminated array of channel ids to unsubscribe from

• returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

To unsubscribe from all channels on the server call

unsigned int ts3client_requestChannelUnsubscribeAll(uint64 serverConnectionHandlerID, const char *returnCode)

Remove subscription from all channels. No longer receiving updates to clients outside of own channel.

The current channel will always be subscribed and you will always receive updates about clients in the current channel. You will receive an onServerErrorEvent with the passed returnCode indicating whether or not the operation was successful.

Parameters:

• serverConnectionHandlerID – the connection handler on which to unsubscribe from all channels

• returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Note

Even when unsubscribing from all channels, the client will still be subscribed to their current channel!

Check subscription status

To check if we are currently subscribed to a particular channel, check its CHANNEL_FLAG_ARE_SUBSCRIBED property using ts3client_getChannelVariableAsInt().

Example

int isSubscribed = -1;

ts3client_getChannelVariableAsInt(scHandlerID, channelID, CHANNEL_FLAG_ARE_SUBSCRIBED, &isSubscribed);
if (isSubscribed > 0) {} // Subscribed
else if (isSubscribed == 0) {} // Not subscribed
else {} // Error, likely not connected.

Callbacks

The following callbacks are called as a result of subscribing to or unsubscribing from a channel

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onClientMoveSubscriptionEvent)(uint64 serverConnectionHandlerID, anyID clientID, uint64 oldChannelID, uint64 newChannelID, int visibility)

called after subscribing to or unsubscribing from a channel. Called once for every client that is in the (un)subscribed channel at this time.

Informs you about newly visible clients after subribing to a channel. Informs about clients that we will no longer receive information about.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param clientID:

id of the client

Param oldChannelID:

id of the channel that the client was in last time we saw the client.

Param newChannelID:

id of the channel the client is currently in.

Param visibility:

whether we can see the client or not. One of the values from the Visibility enum. Allows to distinguish whether this callback was called after a subscribe or unsubscribe.

void (*onChannelSubscribeEvent)(uint64 serverConnectionHandlerID, uint64 channelID)

called when a channel was successfully subscribed by us

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

id of the channel we subscribed to

void (*onChannelSubscribeFinishedEvent)(uint64 serverConnectionHandlerID)

called after all channels we attempted to subscribe to are subscribed.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

void (*onChannelUnsubscribeEvent)(uint64 serverConnectionHandlerID, uint64 channelID)

called after we unsubscribed from a channel

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

id of the channel we unsubscribed from. Will no longer receive updates about clients in this channel.

void (*onChannelUnsubscribeFinishedEvent)(uint64 serverConnectionHandlerID)

called after all channels we attempted to unsubscribe from are unsubscribed

Param serverConnectionHandlerID:

specifies on which connection the callback was called