Channel information

Querying and modifying information related to channels is similar to dealing with clients.

Available properties are described in the ChannelProperties enum.

Note

The server always has all the information about all channels.

Limitations regarding availability mentioned for the variables are thus of no concern for the server.

Query channel information

To query channel information use one of the following functions, depending on the type of the information you want to query.

unsigned int ts3server_getChannelVariableAsInt(uint64 serverID, uint64 channelID, enum ChannelProperties flag, int *result)

get value of a channel variable as integer.

Not all variables are available as integer, some are only available as string or unsigned 64 bit integer.

Parameters:

  • serverID – specifies the server the channel is located on

  • channelID – the id of the channel to get the variable for

  • flag – specifies which variable to retrieve. One of the values from the ChannelProperties enum

  • result – address of a variable to receive the value of the queried variable.

Returns:

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

unsigned int ts3server_getChannelVariableAsUInt64(uint64 serverID, uint64 channelID, enum ChannelProperties flag, uint64 *result)

get value of a channel variable as unsigned 64 bit integer.

Not all variables are available as unsigned 64 bit integer, some are only available as string or integer.

Parameters:

  • serverID – specifies the server the channel is located on

  • channelID – the id of the channel to get the variable for

  • flag – specifies which variable to retrieve. One of the values from the ChannelProperties enum

  • result – address of a variable to receive the value of the queried variable.

Returns:

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

unsigned int ts3server_getChannelVariableAsString(uint64 serverID, uint64 channelID, enum ChannelProperties flag, char **result)

get value of a channel variable as string.

Not all variables are available as string, some are only available as integer or unsigned 64 bit integer.

Parameters:

  • serverID – specifies the server the channel is located on

  • channelID – the id of the channel to get the variable for

  • flag – specifies which variable to retrieve. One of the values from the ChannelProperties enum

  • result – address of a variable to receive the value of the queried variable. Memory is allocated by the server library and caller must free it using ts3server_freeMemory

Returns:

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

Examples

Query topic of channel with ID 123:

1uint64 channelID = 123;  /* Channel ID in our exampel */
2char* topic;
3
4if (ts3server_getChannelVariableAsString(serverID, channel, CHANNEL_TOPIC, &topic) == ERROR_ok) {
5    printf("Topic of channel %u is: %s\n", channelID, topic);
6    ts3server_freeMemory(topic);
7}

Setting channel information

Channel properties can be modified with:

unsigned int ts3server_setChannelVariableAsInt(uint64 serverID, uint64 channelID, enum ChannelProperties flag, int value)

set the variable of a channel to a new value.

Call ts3server_flushChannelVariable after having set all variables you need to change.

Parameters:

  • serverID – specifies the server the channel is located on

  • channelID – specifies the channel on which to change the variable

  • flag – specifies which variable to change. One of the values from the ChannelProperties enum

  • value – the new value to set

Returns:

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

unsigned int ts3server_setChannelVariableAsUInt64(uint64 serverID, uint64 channelID, enum ChannelProperties flag, uint64 value)

set a channel variable

Call ts3server_flushChannelVariable after having set all variables you need to change.

Parameters:

  • serverID – the server on which the channel is located

  • channelID – the id of the channel to set the variable for

  • flag – specifies which variable to set. One of the values from the ChannelProperties enum

  • value – the new value to set

Returns:

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

unsigned int ts3server_setChannelVariableAsString(uint64 serverID, uint64 channelID, enum ChannelProperties flag, const char *value)

Call ts3server_flushChannelVariable after having set all variables you need to change.

Parameters:

  • serverID – the server on which the channel is located

  • channelID – the id of the channel to set the variable for

  • flag – specifies which variable to set. One of the values from the ChannelProperties enum

  • value – the new value to set

Returns:

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

Important

After modifying one or more channel variables, you must flush the changes using ts3server_flushChannelVariable().

The idea behind flushing is, one can modify multiple values by calling ts3server_setChannelVariableAsString(), ts3server_setChannelVariableAsInt() and ts3server_setChannelVariableAsUInt64() multiple times for a channel and then apply all changes in one step.

Examples

Change the channel name and topic:

 1/* Modify channel name */
 2if (ts3server_setChannelVariableAsString(serverID, channelID, CHANNEL_NAME, "New channel name") != ERROR_ok) {
 3    printf("Error setting channel name\n");
 4}
 5
 6/* Modify channel topic */
 7if (ts3server_setChannelVariableAsString(serverID, channelID, CHANNEL_TOPIC, "New channel topic") != ERROR_ok) {
 8    printf("Error setting channel topic\n");
 9}
10
11/* Flush changes */
12if (ts3server_flushChannelVariable(serverID, channelID) != ERROR_ok) {
13    printf("Error flushing channel variable\n");
14}