Channel information

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

Available properties are described in the ChannelProperties enum.

Query channel information

unsigned int ts3client_getChannelVariableAsInt(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, int *result)

Retrieve the value of a channel property as integer.

Not all properties are available as integer. Some are only available as string or unsigned 64 bit integer.

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

  • channelID – the channel of which to retrieve the property

  • flag – specifies which property to retrieve. One of the values from the ChannelProperties or ChannelPropertiesRare enum

  • result – address of a variable to receive the result on success

Returns:

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

unsigned int ts3client_getChannelVariableAsUInt64(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, uint64 *result)

Retrieve the value of a channel property as unsigned 64 bit integer.

Not all properties are available as string. Some are only available as integer or string.

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

  • channelID – the channel of which to retrieve the property

  • flag – specifies which property to retrieve. One of the values from the ChannelProperties or ChannelPropertiesRare enum

  • result – address of a variable to receive the result on success

Returns:

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

unsigned int ts3client_getChannelVariableAsString(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, char **result)

Retrieve the value of a channel property as string.

Not all properties are available as string. Some are only available as integer or unsigned 64 bit integer.

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

  • channelID – the channel of which to retrieve the property

  • flag – specifies which property to retrieve. One of the values from the ChannelProperties or ChannelPropertiesRare enum

  • result – address of a variable to receive the result on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

To get the channel id from the channel path (e.g. ‘Lobby/AFK channel’) use

unsigned int ts3client_getChannelIDFromChannelNames(uint64 serverConnectionHandlerID, char **channelNameArray, uint64 *result)

Get the channel id for the given channel path.

Parameters:

  • serverConnectionHandlerID – connection handler on which to find the channel

  • channelNameArray – zero terminated array of c strings describing the channel path. Like {“Main channel”, “sub channel”, null}

  • result – address of a variable to receive the channel id on success

Returns:

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

Editing channel information

Channel properties can be modified with the following functions

unsigned int ts3client_setChannelVariableAsInt(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, int value)

set a new value for an integer channel property

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

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

  • flag – specifies which property to set. One of the values from the ChannelProperties or ChannelPropertiesRare enums

  • value – the new value to set

Returns:

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

unsigned int ts3client_setChannelVariableAsUInt64(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, uint64 value)

set a new value for an unsigned 64 bit channel property

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

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

  • flag – specifies which property to set. One of the values from the ChannelProperties or ChannelPropertiesRare enums

  • value – the new value to set

Returns:

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

unsigned int ts3client_setChannelVariableAsString(uint64 serverConnectionHandlerID, uint64 channelID, size_t flag, const char *value)

set a new value for a string channel property

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

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

  • flag – specifies which property to set. One of the values from the ChannelProperties or ChannelPropertiesRare enums

  • 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 have to flush the changes to the server.

unsigned int ts3client_flushChannelUpdates(uint64 serverConnectionHandlerID, uint64 channelID, const char *returnCode)

Inform server of changes to channel properties.

After all desired changes have been done using ts3client_setChannelVariableAsInt, ts3client_setChannelVariableAsUInt64 or ts3client_setChannelVariableAsString call this function to send the changes to the server and publish them to other clients. Prior to calling this function the channel property changes will not have any effect.

Parameters:

  • serverConnectionHandlerID – connection handler on which the channel is located

  • channelID – id of the channel to publish updates for

  • 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

Examples

As example, to change the channel name and topic:

 1/* Modify data 1 */
 2if (ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_NAME, "Other channel name") != ERROR_ok) {
 3    printf("Error setting channel name\n");
 4    return;
 5}
 6
 7/* Modify data 2 */
 8if (ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_TOPIC, "Other channel topic") != ERROR_ok) {
 9    printf("Error setting channel topic\n");
10    return;
11}
12
13/* Flush changes */
14if (ts3client_flushChannelUpdates(scHandlerID, channelID) != ERROR_ok) {
15    printf("Error flushing channel updates\n");
16    return;
17}

Callbacks

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 (*onUpdateChannelEvent)(uint64 serverConnectionHandlerID, uint64 channelID)

called when new data for a channel was received from the server

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

id of the channel that new information was received for

void (*onUpdateChannelEditedEvent)(uint64 serverConnectionHandlerID, uint64 channelID, anyID invokerID, const char *invokerName, const char *invokerUniqueIdentifier)

called when a channel was edited on the server

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

the id of the channel that was edited

Param invokerID:

client id that edited the channel. 0 if done by the server

Param invokerName:

utf8 encoded c string containing the display name of the client editing the channel

Param invokerUniqueIdentifier:

utf8 encoded c string containing the uid of the client that edited the channel

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

called when the channel description of a channel has changed.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

the channel for which the description has changed

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

called when a channel password was changed. Can be used to invalidate cached passwords previously stored for the channel.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

id of the channel the password was changed on