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
;
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.
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.
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.
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 */