Channel information

Channel information
á	Retrieve and store 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;

Parameters

serverConnectionHandlerID
ID of the server connection handler on which the information for the specified channel is requested.
channelID
ID of the channel whose property is queried.
flag
Channel propery to query, see below.
result
Address of a variable which receives the result value of type int, uint64 or string, depending on which function is used. In case of a string, memory must be released using ts3client_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. Clients need to request updating this variable for a specified channel using:
unsigned int ts3client_requestChannelDescription( serverConnectionHandlerID, á
á channelID, á
á returnCode); á
uint64 serverConnectionHandlerID;
uint64 channelID;
const char* returnCode;
á
CHANNEL_PASSWORD
String: Optional password for password-protected channels.
Note
Clients can only set this value, but not query it.
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)
See Sound codecs.
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.
See Encoder options.
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.
For more information please see the chapter Channel sorting.
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 ts3client_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).

	Note
Clients can only set this value, but not query it.

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;

Parameters

serverConnectionHandlerID
ID of the server connection handler 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. Depending on which function is used, the value can be of type int, uint64 or string.

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

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;

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)`;	á

uint64 serverConnectionHandlerID;
uint64 channelID;
anyID invokerID;
const char* invokerName;
const char* invokerUniqueIdentifier;

Parameters

serverConnectionHandlerID
ID of the server connection handler on which the channel has been edited.
channelID
ID of edited channel.
invokerID
ID of the client who edited the channel.
invokerName
String with the name of the client who edited the channel.
invokerUniqueIdentifier
String with the unique ID of the client who edited the channel.

To find the channel ID from a channels path:

`unsigned int ts3client_getChannelIDFromChannelNames(`	`serverConnectionHandlerID`,	á
á	`channelNameArray`,	á
á	`result)`;	á

uint64 serverConnectionHandlerID;
char** channelNameArray;
uint64* result;

Parameters

serverConnectionHandlerID
ID of the server connection handler on which the channel ID is queried.
channelNameArray
Array defining the position of the channel: "grandparent", "parent", "channel", "". The array is terminated by an empty string.
result
Address of a variable which receives the queried channel ID.

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.

`unsigned int ts3client_requestChannelDescription(`	`serverConnectionHandlerID`,	á
á	`channelID`,	á
á	`returnCode)`;	á

á		á
Retrieve and store informationá		áChannel sorting