Channel information

Query channel information

Querying and modifying information related to channels is similar to dealing with clients. The parameter flag is defined by the enum ChannelProperties. The functions to query channel information are:

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

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

Parameters

  • serverID

    ID of the virtual server on which the channel property is queried.

  • channelID

    ID of the queried channel.

  • flag

    Channel propery to query, see below.

  • result

    Address of a variable which receives the result value as int or string, depending on which function is used. In case of a string, memory must be released using ts3server_freeMemory, unless an error occured.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h. For the string version: If an error has occured, the result string is uninitialized and must not be released.

The parameter flag specifies the type of queried information. It is defined by the enum ChannelProperties:

enum ChannelProperties {
  CHANNEL_NAME = 0,             //Available for all channels that are "in view", always up-to-date
  CHANNEL_TOPIC,                //Available for all channels that are "in view", always up-to-date
  CHANNEL_DESCRIPTION,          //Must be requested (=> requestChannelDescription)
  CHANNEL_PASSWORD,             //not available client side
  CHANNEL_CODEC,                //Available for all channels that are "in view", always up-to-date
  CHANNEL_CODEC_QUALITY,        //Available for all channels that are "in view", always up-to-date
  CHANNEL_MAXCLIENTS,           //Available for all channels that are "in view", always up-to-date
  CHANNEL_MAXFAMILYCLIENTS,     //Available for all channels that are "in view", always up-to-date
  CHANNEL_ORDER,                //Available for all channels that are "in view", always up-to-date
  CHANNEL_FLAG_PERMANENT,       //Available for all channels that are "in view", always up-to-date
  CHANNEL_FLAG_SEMI_PERMANENT,  //Available for all channels that are "in view", always up-to-date
  CHANNEL_FLAG_DEFAULT,         //Available for all channels that are "in view", always up-to-date
  CHANNEL_FLAG_PASSWORD,        //Available for all channels that are "in view", always up-to-date
  CHANNEL_CODEC_LATENCY_FACTOR, //Available for all channels that are "in view", always up-to-date
  CHANNEL_CODEC_IS_UNENCRYPTED, //Available for all channels that are "in view", always up-to-date
  CHANNEL_ENDMARKER,
};
  • CHANNEL_NAME

    String: Name of the channel.

  • CHANNEL_TOPIC

    String: Single-line channel topic.

  • CHANNEL_DESCRIPTION

    String: Optional channel description. Can have multiple lines.

  • CHANNEL_PASSWORD

    String: Password for password-protected channels.

    If a password is set or removed by modifying this field, CHANNEL_FLAG_PASSWORD will be automatically adjusted.

  • CHANNEL_CODEC

    Int (0-3): Codec used for this channel:

    • 0 - Speex Narrowband (8 kHz)

    • 1 - Speex Wideband (16 kHz)

    • 2 - Speex Ultra-Wideband (32 kHz)

  • CHANNEL_CODEC_QUALITY

    Int (0-10): Quality of channel codec of this channel. Valid values range from 0 to 10, default is 7. Higher values result in better speech quality but more bandwidth usage.

  • CHANNEL_MAXCLIENTS

    Int: Number of maximum clients who can join this channel.

  • CHANNEL_MAXFAMILYCLIENTS

    Int: Number of maximum clients who can join this channel and all subchannels.

  • CHANNEL_ORDER

    Int: Defines how channels are sorted in the GUI. Channel order is the ID of the predecessor channel after which this channel is to be sorted. If 0, the channel is sorted at the top of its hirarchy.

  • CHANNEL_FLAG_PERMANENT / CHANNEL_FLAG_SEMI_PERMANENT

    Concerning channel durability, there are three types of channels:

    • Temporary

      Temporary channels have neither the CHANNEL_FLAG_PERMANENT nor CHANNEL_FLAG_SEMI_PERMANENT flag set. Temporary channels are automatically deleted by the server after the last user has left and the channel is empty. They will not be restored when the server restarts.

    • Semi-permanent

      Semi-permanent channels are not automatically deleted when the last user left but will not be restored when the server restarts.

    • Permanent

      Permanent channels will be restored when the server restarts.

  • CHANNEL_FLAG_DEFAULT

    Int (0/1): Channel is the default channel. There can only be one default channel per server. New users who did not configure a channel to join on login in ts3server_startConnection will automatically join the default channel.

  • CHANNEL_FLAG_PASSWORD

    Int (0/1): If set, channel is password protected. The password itself is stored in CHANNEL_PASSWORD.

  • CHANNEL_CODEC_LATENCY_FACTOR

    (Int: 1-10): Latency of this channel. This allows to increase the packet size resulting in less bandwidth usage at the cost of higher latency. A value of 1 (default) is the best setting for lowest latency and best quality. If bandwidth or network quality are restricted, increasing the latency factor can help stabilize the connection. Higher latency values are only possible for low-quality codec and codec quality settings.

    For best voice quality a low latency factor is recommended.

  • CHANNEL_CODEC_IS_UNENCRYPTED

    Int (0/1): If 1, this channel is not using encrypted voice data. If 0, voice data is encrypted for this channel. Note that channel voice data encryption can be globally disabled or enabled for the virtual server. Changing this flag makes only sense if global voice data encryption is set to be configured per channel as CODEC_ENCRYPTION_PER_CHANNEL (the default behaviour).

Example 1: Query topic of channel with ID 123:

uint64 channelID = 123;  /* Channel ID in our exampel */
char topic;

if(ts3server_getChannelVariableAsString(serverID, channel, CHANNEL_TOPIC, &topic) == ERROR_ok) {
    printf("Topic of channel %u is: %s\n", channelID, topic);
    ts3server_freeMemory(topic);
}

Setting channel information

Channel properties can be modified with:

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

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

Parameters

  • serverConnectionHandlerID

    ID of the virtual server on which the information for the specified channel should be changed.

  • channelID

    ID of the channel whoses property should be changed.

  • flag

    Channel propery to change, see above.

  • value

    Value the channel property should be changed to.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

[Important]Important

After modifying one or more channel variables, you must flush the changes.

unsigned int ts3server_flushChannelVariable(serverID,  
 channelID); 
uint64 serverID;
uint64 channelID;
 

Example: Change the channel name and topic:

/* Modify channel name */
if(ts3server_setChannelVariableAsString(serverID, channelID, CHANNEL_NAME,  "New channel name") != ERROR_ok) {
    printf("Error setting channel name\n");
}

/* Modify channel topic */
if(ts3server_setChannelVariableAsString(serverID, channelID, CHANNEL_TOPIC, "New channel topic") != ERROR_ok) {
    printf("Error setting channel topic\n");
}

/* Flush changes */
if(ts3server_flushChannelVariable(serverID, channelID) != ERROR_ok) {
    printf("Error flushing channel variable\n");
}