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); 
anyID serverConnectionHandlerID;
anyID channelID;
ChannelProperties flag;
int* result;
 

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

Parameters

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_ENDMARKER,
};


To modify channel data use

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

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

Parameters

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); 
anyID serverConnectionHandlerID;
anyID channelID;
 

Parameters

  • serverConnectionHandlerID

    ID of the server connection handler to which the channel changes should be flushed.

  • channelParentID

    ID of the channel of which the changed properties should be flushed.

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

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); 
anyID serverConnectionHandlerID;
anyID channelID;
anyID invokerID;
const char* invokerName;
const char* invokerUniqueIdentifier;
 

Parameters


To find the channel ID from a channels path:

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

Parameters

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