Alternative way to create virtual servers

In addition to the previously mentioned way to start a virtual server using ts3server_startVirtualServer, there is an alternative way to create a virtual server. The advantage of this method is the possibility to restore the complete channel structure on server creation including the channel IDs in one step. This allows taking and restoring server snapshots including the channel tree.

[Note]Note

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


First, a struct TS3VirtualServerCreationParams has to be created, which will be filled with essential and optional server parameters and then used to create and start the virtual server. Create a new virtual server parameter structure with the function:

unsigned int ts3server_makeVirtualServerCreationParams(result); 
struct TS3VirtualServerCreationParams** result;
 

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 the struct TS3VirtualServerCreationParams has been created, it needs to be filled with the essential parameters to create a new virtual server. Essential parameters include server port, IP, the key pair, max clients, number of channels we want to start the server with and the virtual server ID.

Set the essential parameters with the function:

unsigned int ts3server_setVirtualServerCreationParams(virtualServerCreationParams,  
 serverPort,  
 serverIp,  
 serverKeyPair,  
 serverMaxClients,  
 channelCount,  
 serverID); 
struct TS3VirtualServerCreationParams* virtualServerCreationParams;
unsigned int serverPort;
const char* serverIp;
const char* serverKeyPair;
unsigned int serverMaxClients;
unsigned int channelCount;
uint64 serverID;
 

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


After essential virtual server parameters have been defined with ts3server_setVirtualServerCreationParams, additional parameters can be filled. For that, first a struct TS3Variables needs to be queried from the TS3VirtualServerCreationParams, in which the additional paramters will be written using the functions ts3server_setVariableAsInt, ts3server_setVariableAsUInt64 and ts3server_setVariableAsString.

Query the TS3Variables with:

unsigned int ts3server_getVirtualServerCreationParamsVariables(virtualServerCreationParams,  
 result); 
struct TS3VirtualServerCreationParams* virtualServerCreationParams;
struct TS3Variables** result;
 

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


Once you have a pointer to a valid struct TS3Variables, you can query and modify various parameters with one of the following functions. Select the proper function depending of the type of the parameter you want to query or modify. The parameter flag is a value VIRTUALSERVER_* defined in the enum VirtualServerProperties.

Query parameter of the struct TS3Variables as integer:

unsigned int ts3server_getVariableAsInt(var,  
 flag,  
 result); 
struct TS3Variables* var;
int flag;
int* result;
 

Query parameter of the struct TS3Variables as uint64:

unsigned int ts3server_getVariableAsUInt64(var,  
 flag,  
 result); 
struct TS3Variables* var;
int flag;
uint64* result;
 

Query parameter of the struct TS3Variables as string:

unsigned int ts3server_getVariableAsString(var,  
 flag,  
 result); 
struct TS3Variables* var;
int flag;
char** result;
 

Set parameter of the struct TS3Variables as integer:

unsigned int ts3server_setVariableAsInt(var,  
 flag,  
 value); 
struct TS3Variables* var;
int flag;
int value;
 

Set parameter of the struct TS3Variables as uint64:

unsigned int ts3server_setVariableAsUInt64(var,  
 flag,  
 value); 
struct TS3Variables* var;
int flag;
uint64 value;
 

Set parameter of the struct TS3Variables as string:

unsigned int ts3server_setVariableAsString(var,  
 flag,  
 value); 
struct TS3Variables* var;
int flag;
const char* value;
 

All these functions return ERROR_ok on success, otherwise an error code as defined in public_errors.h.


Example setting the virtual server name:

if(ts3server_setVariableAsString(vars, VIRTUALSERVER_NAME, "My Server") != ERROR_ok) {
    printf("Failed to set virtual server name: %d\n", error);
}


After setting global virtual server parameters we are ready to initialize the channel tree. In a loop, for each channel you retrieve a struct TS3ChannelCreationParams and fill it with the desired channel parameters, including the channel ID.

[Note]Note

The number of created channels must match exactly the previously defined channelCount in ts3server_setVirtualServerCreationParams.


For each channel get the channel creation param for the given channel index. This channel param structs are subobjects created inside the server creation params, so do not delete them.

unsigned int ts3server_getVirtualServerCreationParamsChannelCreationParams(virtualServerCreationParams,  
 channelIdx,  
 result); 
struct TS3VirtualServerCreationParams* virtualServerCreationParams;
unsigned int channelIdx;
struct TS3ChannelCreationParams** result;
 

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


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;
 

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 parameters in a way similar as above for the virtual server. Retrieve a struct TS3Variables for this channel and fill it with the above mentioned functions ts3server_setVariableAsInt, ts3server_setVariableAsUInt64 and ts3server_setVariableAsString.

Retrieve a struct TS3Variables with

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

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


Finally, after setting up server and channel parameters, create the virtual server including the channel tree in one step with

unsigned int ts3server_createVirtualServer2(virtualServerCreationParams,  
 flags,  
 result); 
struct TS3VirtualServerCreationParams* virtualServerCreationParams;
enum VirtualServerCreateFlags flags;
uint64* result;
 

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