The Server Lib offers a subset of client-side functionality to create, move and delete channels directly on the server.
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.
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 |
---|---|
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
.
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.
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.
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 */