Channel and client manipulation

The Server Lib offers a subset of client-side functionality to create, move and delete channels directly on the server.

Creating a new channel

To create a channel, first set the desired channel variables using ts3server_setChannelVariableAsInt and ts3server_setChannelVariableAsString. Pass zero as the channel ID parameter.

Next send the request to the server by calling:

unsigned int ts3server_flushChannelCreation(serverID,  
 channelParentID,  
 result); 
uint64 serverID;
uint64 channelParentID;
uint64* result;
 

  • serverID

    ID of the virtual server on which that channel should be created.

  • channelParentID

    ID of the parent channel, if the new channel is to be created as subchannel. Pass zero if the channel should be created as top-level channel.

  • result

    Address of a variable that receives the ID of the newly created channel.

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

Example code to create a channel:

#define CHECK_ERROR(x) if((error = x) != ERROR_ok) { goto on_error; }

int createChannel(uint64 serverID, uint64 parentChannelID, const char* name, const char* topic,
                  const char* description, const char* password, int codec, int codecQuality,
                  int maxClients, int familyMaxClients, int order, int perm, int semiperm,
                  int default) {
  unsigned int error;
  uint64 newChannelID;

  /* Set channel data, pass 0 as channel ID */
  CHECK_ERROR(ts3server_setChannelVariableAsString(serverID, 0, CHANNEL_NAME, name));
  CHECK_ERROR(ts3server_setChannelVariableAsString(serverID, 0, CHANNEL_TOPIC, topic));
  CHECK_ERROR(ts3server_setChannelVariableAsString(serverID, 0, CHANNEL_DESCRIPTION, description));
  CHECK_ERROR(ts3server_setChannelVariableAsString(serverID, 0, CHANNEL_PASSWORD, password));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_CODEC, codec));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_CODEC_QUALITY, codecQuality));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_MAXCLIENTS, maxClients));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_MAXFAMILYCLIENTS, familyMaxClients));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_ORDER, order));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_FLAG_PERMANENT, perm));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_FLAG_SEMI_PERMANENT, semiperm));
  CHECK_ERROR(ts3server_setChannelVariableAsInt   (serverID, 0, CHANNEL_FLAG_DEFAULT, default));

  /* Flush changes to server */
  CHECK_ERROR(ts3server_flushChannelCreation(serverID, parentChannelID, &newChannelID));

  printf("Created new channel with ID: %u\n", newChannelID);
  return 0;  /* Success */

on_error:
  printf("Error creating channel: %d\n", error);
  return 1;  /* Failure */
}

After creating a channel, the event onChannelCreated is called.

Alternative way to create a new channel

There is an alternative API available for channel creation, which is very similar to the alternative virtual server creation API. The idea is to create a TS3ChannelCreationParams, query the attached struct TS3Variables, fill it with desired parameters and finally call ts3server_createChannel.

[Note]Note

For a complete example please see the “server_creation_params” sample code in the SDK package.


First, create a TS3ChannelCreationParams with

unsigned int ts3server_makeChannelCreationParams(result); 
struct TS3ChannelCreationParams** result;
 

  • result

    Address of a variable that receives the created struct TS3ChannelCreationParams.

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


Once we have a struct TS3ChannelCreationParams for this channel, we can start to fill it in two steps. Step 1 is setting the essential data, step 2 is setting optional additional data.

Essential parameters are channel parent ID and channel ID. Set them with

unsigned int ts3server_setChannelCreationParams(channelCreationParams,  
 channelParentID,  
 channelID); 
struct TS3ChannelCreationParams* channelCreationParams;
uint64 channelParentID;
uint64 channelID;
 

  • channelCreationParams

    Address of the struct TS3ChannelCreationParams, where the parameters should be set.

    channelParentID

    ID of the parent channel. Set 0 to create this as top-level channel.

    channelID

    ID of the channel to create. This allows you to setup a complete channel tree with predefined channel IDs, unlike the legacy way to create channels where the channel ID is automatically assigned by the server.

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


After setting the essential parameters, we can set optional additional channel parameters. Retrieve a struct TS3Variables for this channel and fill it with ts3server_setVariableAsInt, ts3server_setVariableAsUInt64 and ts3server_setVariableAsString, as described here.

Retrieve a struct TS3Variables with

unsigned int ts3server_getChannelCreationParamsVariables(channelCreationParams,  
 result); 
struct TS3ChannelCreationParams* channelCreationParams;
struct TS3Variables** result;
 

  • channelCreationParams

    Address of the struct TS3ChannelCreationParams, for which we want to retrieve the TS3Variables.

    result

    Address to be filled with the struct TS3Variables we want to retrieve.

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


Finally, after setting up channel parameters, create the channel in one step with

unsigned int ts3server_createChannel(serverID,  
 channelCreationParams,  
 flags,  
 result); 
uint64 serverID;
struct TS3ChannelCreationParams* channelCreationParams;
enum ChannelCreateFlags flags;
uint64* result;
 

  • channelCreationParams

    Address of the struct TS3ChannelCreationParams with the creation parameters for this .

    flags

    Defines if the channel password is passed as plaintext or already encrypted. If already encrypted, this is the password retrieved via the channel variable CHANNEL_PASSWORD, which is returned as encrypted password. In this case you would specify the password on channel creation as already encrypted to avoid it being encrypted automatically a second time.

    enum ChannelCreateFlags{ 
        CHANNEL_CREATE_FLAG_NONE                = 0x000,
        CHANNEL_CREATE_FLAG_PASSWORDS_ENCRYPTED = 0x001,
    };

    result

    Address to be filled with the created channel ID.

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

Deleting a channel

A channel can be deleted by the server with

unsigned int ts3server_channelDelete(serverID,  
 channelID,  
 force); 
uint64 serverID;
uint64 channelID;
int force;
 

  • serverID

    The ID of the virtual server on which the channel should be deleted.

  • channelID

    The ID of the channel to be deleted.

  • force

    If 1, first move all clients inside the specified channel to the default channel and then delete the specific channel. If false, deleting a channel with joined clients will fail.

    If 0, the server will refuse to a channel that is not empty.

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

After successfully deleting a channel, the event onChannelDeleted is called for every deleted channel.

Moving a channel

To move a channel to a new parent channel, call

unsigned int ts3server_channelMove(serverID,  
 channelID,  
 newChannelParentID); 
uint64 serverID;
uint64 channelID;
uint64 newChannelParentID;
 

  • serverID

    ID of the virtual server on which the channel should be moved.

  • channelID

    ID of the channel to be moved.

  • newChannelParentID

    ID of the parent channel where the moved channel is to be inserted as child. Use 0 to insert as top-level channel.

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

After the channel has been moved, the event onChannelEdited is called.

Moving clients

Clients can be moved server-side to another channel, in addition to the client-side functionality offered by the Client Lib. To move one or multiple clients to a new channel, call:

unsigned int ts3server_clientMove(serverID,  
 newChannelID,  
 clientIDArray); 
uint64 serverID;
uint64 newChannelID;
const anyID* clientIDArray;
 

  • serverID

    ID of the virtual server on which the client should be moved.

  • newChannelID

    ID of the channel in which the clients should be moved into.

  • newChannelParentID

    Zero-terminated array with the IDs of the clients to be moved.

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

After the channel has been moved, the event onClientMoved is called.

Example to move a single client to another channel:

anyID clientIDArray[2];  /* One client plus terminating zero as end-marker */
uint64 newChannelID;
unsigned int error;

clientIDArray[0] = clientID;  /* Client to move */
clientIDArray[1] = 0;  /* End marker */

if((error = ts3server_clientMove(serverID, newChannelID, channelIDArray)) != ERROR_ok) {
    /* Handle error */
    return;
}

/* Client moved successfully */