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;
 

Parameters

  • 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.

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;
 

Parameters

  • 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;
 

Parameters

  • 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;
 

Parameters

  • 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 */