Channel subscriptions
| Interacting with the server |

### Channel subscriptions

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 to 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