Creating a new channel

To create a channel, set the desired channel variables using one of the following functions, passing 0 to the channel id parameter:

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

Request creation

To request the server to actually create the channel call

unsigned int ts3client_flushChannelCreation(uint64 serverConnectionHandlerID, uint64 channelParentID, const char *returnCode)

Create the channel on the server.

After setting all the desired properties on the channel, call this function to actually create the channel on the server

Parameters:

  • serverConnectionHandlerID – connection handler on which to create the channel

  • channelParentID – id of the channel this channel should be a sub channel of. Pass 0 to create a root channel.

  • 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

Callback

If the channel was successfully created the following callback will be called

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 (*onNewChannelCreatedEvent)(uint64 serverConnectionHandlerID, uint64 channelID, uint64 channelParentID, anyID invokerID, const char *invokerName, const char *invokerUniqueIdentifier)

called when a new channel was created

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param channelID:

the id of the new channel

Param channelParentID:

the id of the parent channel for the newly created channel. 0 if the channel is a root channel.

Example

Example code to create a channel:

 1#define CHECK_ERROR(x) if ((error = x) != ERROR_ok) { goto on_error; }
 2
 3int createChannel(uint64 scHandlerID, uint64 parentChannelID, const char* name, const char* topic,
 4                  const char* description, const char* password, int codec, int codecQuality,
 5                  int maxClients, int familyMaxClients, int order, int perm,
 6                  int semiperm, int default) {
 7  unsigned int error;
 8
 9  /* Set channel data, pass 0 as channel ID */
10  CHECK_ERROR(ts3client_setChannelVariableAsString(scHandlerID, 0, CHANNEL_NAME, name));
11  CHECK_ERROR(ts3client_setChannelVariableAsString(scHandlerID, 0, CHANNEL_TOPIC, topic));
12  CHECK_ERROR(ts3client_setChannelVariableAsString(scHandlerID, 0, CHANNEL_DESCRIPTION, desc));
13  CHECK_ERROR(ts3client_setChannelVariableAsString(scHandlerID, 0, CHANNEL_PASSWORD, password));
14  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_CODEC, codec));
15  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_CODEC_QUALITY, codecQuality));
16  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_MAXCLIENTS, maxClients));
17  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_MAXFAMILYCLIENTS, familyMaxClients));
18  CHECK_ERROR(ts3client_setChannelVariableAsUInt64(scHandlerID, 0, CHANNEL_ORDER, order));
19  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_FLAG_PERMANENT, perm));
20  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_FLAG_SEMI_PERMANENT, semiperm));
21  CHECK_ERROR(ts3client_setChannelVariableAsInt   (scHandlerID, 0, CHANNEL_FLAG_DEFAULT, default));
22
23  /* Flush changes to server */
24  CHECK_ERROR(ts3client_flushChannelCreation(scHandlerID, parentChannelID));
25  return 0;  /* Success */
26
27on_error:
28  printf("Error creating channel: %d\n", error);
29  return 1;  /* Failure */
30}