Channel subscriptions

Channel subscriptions
á	Interacting with the server	á

Normally a user only sees other clients who are in the same channel. Clients joining or leaving other channels or changing status are not displayed. To offer a way to get notifications about clients in other channels, a user can subscribe to other channels. It would also be 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 reduce network traffic. Also subscriptions allow to usage “private” channels, whose members cannot be seen by other users.

	Note
	A client is automatically subscribed to the current channel.

To subscribe to a list of channels (zero-terminated array of channel IDs) call:

`unsigned int ts3client_requestChannelSubscribe(`	`serverConnectionHandlerID`,	á
á	`channelIDArray`,	á
á	`returnCode)`;	á

uint64 serverConnectionHandlerID;
const uint64* channelIDArray;
const char* returnCode;

To unsubscribe from a list of channels (zero-terminated array of channel IDs) call:

`unsigned int ts3client_requestChannelUnsubscribe(`	`serverConnectionHandlerID`,	á
á	`channelIDArray`,	á
á	`returnCode)`;	á

uint64 serverConnectionHandlerID;
const uint64* channelIDArray;
const char* returnCode;

To subscribe to all channels on the server call:

`unsigned int ts3client_requestChannelSubscribeAll(`	`serverConnectionHandlerID`,	á
á	`returnCode)`;	á

uint64 serverConnectionHandlerID;
const char* returnCode;

To unsubscribe from all channels on the server call:

`unsigned int ts3client_requestChannelUnsubscribeAll(`	`serverConnectionHandlerID`,	á
á	`returnCode)`;	á

uint64 serverConnectionHandlerID;
const char* returnCode;

To check if a channel is currently subscribed, check the channel property CHANNEL_FLAG_ARE_SUBSCRIBED with ts3client_getChannelVariableAsInt:

int isSubscribed;

if(ts3client_getChannelVariableAsInt(scHandlerID, channelID, CHANNEL_FLAG_ARE_SUBSCRIBED, &isSubscribed)
   != ERROR_ok) {
    /* Handle error */
}

The following event will be sent for each successfully subscribed channel:

`void onChannelSubscribeEvent(`	`serverConnectionHandlerID`,	á
á	`channelID)`;	á

uint64 serverConnectionHandlerID;
uint64 channelID;

Provided for convinience, to mark the end of mulitple calls to onChannelSubscribeEvent when subscribing to several channels, this event is called:

void onChannelSubscribeFinishedEvent( serverConnectionHandlerID); á

uint64 serverConnectionHandlerID;

The following event will be sent for each successfully unsubscribed channel:

`void onChannelUnsubscribeEvent(`	`serverConnectionHandlerID`,	á
á	`channelID)`;	á

uint64 serverConnectionHandlerID;
uint64 channelID;

Similar like subscribing, this event is a convinience callback to mark the end of multiple calls to onChannelUnsubscribeEvent:

void onChannelUnsubscribeFinishedEvent( serverConnectionHandlerID); á

uint64 serverConnectionHandlerID;

Once a channel has been subscribed or unsubscribed, the event onClientMoveSubscriptionEvent is sent for each client in the subscribed channel. The event is not to be confused with onClientMoveEvent, which is called for clients actively switching channels.

`void onClientMoveSubscriptionEvent(`	`serverConnectionHandlerID`,	á
á	`clientID`,	á
á	`oldChannelID`,	á
á	`newChannelID`,	á
á	`visibility)`;	á

uint64 serverConnectionHandlerID;
anyID clientID;
uint64 oldChannelID;
uint64 newChannelID;
int visibility;

Parameters

serverConnectionHandlerID
The server connection handler ID for the server where the action occured.
clientID
The client ID.
oldChannelID
ID of the subscribed channel where the client left visibility.
newChannelID
ID of the subscribed channel where the client entered visibility.
visibility
Defined in the enum Visibility
```
enum Visibility {
    ENTER_VISIBILITY = 0,
    RETAIN_VISIBILITY,
    LEAVE_VISIBILITY
};
```
- ENTER_VISIBILITY
  Client entered visibility.
- LEAVE_VISIBILITY
  Client left visibility.
- RETAIN_VISIBILITY
  Does not occur with onClientMoveSubscriptionEvent.

á		á
Kicking clientsá		áMuting clients locally