Channel information
Prev Retrieve and store information Next

Channel information

Querying and modifying information related to channels is similar to dealing with clients. The functions to query channel information are:

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

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

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

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_SECURITY_SALT,        //Sets the options+salt for security hash (SDK only)
  CHANNEL_DELETE_DELAY,         //How many seconds to wait before deleting this channel
  CHANNEL_ENDMARKER,
};


To modify channel data use

unsigned int ts3client_setChannelVariableAsInt(serverConnectionHandlerID,  
 channelID,  
 flag,  
 value); 
uint64 serverConnectionHandlerID;
uint64 channelID;
ChannelProperties flag;
int value;
 

unsigned int ts3client_setChannelVariableAsUInt64(serverConnectionHandlerID,  
 channelID,  
 flag,  
 value); 
uint64 serverConnectionHandlerID;
uint64 channelID;
ChannelProperties flag;
uint64 value;
 

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

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

unsigned int ts3client_flushChannelUpdates(serverConnectionHandlerID,  
 channelID); 
uint64 serverConnectionHandlerID;
uint64 channelID;
 

As example, to change the channel name and topic:

/* Modify data 1 */
if(ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_NAME,
                                        "Other channel name") != ERROR_ok) {
    printf("Error setting channel name\n");
    return;
}

/* Modify data 2 */
if(ts3client_setChannelVariableAsString(scHandlerID, channelID, CHANNEL_TOPIC,
                                        "Other channel topic") != ERROR_ok) {
    printf("Error setting channel topic\n");
    return;
}

/* Flush changes */
if(ts3client_flushChannelUpdates(scHandlerID, channelID) != ERROR_ok) {
    printf("Error flushing channel updates\n");
    return;
}


After a channel was edited using ts3client_setChannelVariableAsInt or ts3client_setChannelVariableAsString and the changes were flushed to the server, the edit is announced with the event:

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


To find the channel ID from a channels path:

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

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

Channel voice data encryption

Voice data can be encrypted or unencrypted. Encryption will increase CPU load, so should be used only when required. Encryption can be configured per channel (the default) or globally enabled or disabled for the whole virtual server. By default channels are sending voice data unencrypted, newly created channels would need to be set to encrypted if required.

To configure the global virtual server encryption settings, modify the virtual server property VIRTUALSERVER_CODEC_ENCRYPTION_MODE to one of the following values: 

enum CodecEncryptionMode {
   CODEC_ENCRYPTION_PER_CHANNEL = 0,  // Default
   CODEC_ENCRYPTION_FORCED_OFF,
   CODEC_ENCRYPTION_FORCED_ON,
};

Voice data encryption per channel can be configured by setting the channel property CHANNEL_CODEC_IS_UNENCRYPTED to 0 (encrypted) or 1 (unencrypted) if global encryption mode is CODEC_ENCRYPTION_PER_CHANNEL. If encryption is forced on or off globally, the channel property will be automatically set by the server.

Prev Up Next
Retrieve and store information Home Channel sorting