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 |
---|---|
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
;result
Address of a variable that receives the created struct TS3VirtualServerCreationParams
.
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
;virtualServerCreationParams
Address of the struct TS3VirtualServerCreationParams
, which was created earlier with ts3server_makeVirtualServerCreationParams
.
serverPort
Port of the virtual server to be created.
serverIp
Comma seperated list of IP addresses to bind the virtual server to. Both IPv4 and IPv6 IPs are supported. Pass “0.0.0.0, ::” to bind the virtual server to all IP addresses.
serverKeyPair
Unique keypair of this server. The first time you start this virtual server, pass an empty string, query the keypair with ts3server_getVirtualServerKeyPair
, then save the keypair locally and pass it the next time as parameter to this function.
serverMaxClients
Maximum numbers clients which can be online on the virtual server at the same time.
channelCount
Number of channels which are immediately created at server start. This value defines how many structs TS3ChannelCreationParams
are available in the function ts3server_getVirtualServerCreationParamsChannelCreationParams
, where the channels will be defined later.
serverID
ID of the virtual server to be created.
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
;virtualServerCreationParams
Address of the struct TS3VirtualServerCreationParams
, which was created earlier with ts3server_makeVirtualServerCreationParams
.
result
Adress of a variable into which the struct TS3Variables
is written.
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 |
---|---|
The number of created channels must match exactly the previously defined |
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
;virtualServerCreationParams
Address of the struct TS3VirtualServerCreationParams
, which was created earlier with ts3server_makeVirtualServerCreationParams
.
channelIdx
Index of the channel we want to address. Index must be in range of the previously specified channelCount
of this virtual server.
result
Address of a struct TS3ChannelCreationParams
, which we are going to fill in the next step.
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
;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 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
;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 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
;virtualServerCreationParams
Address of the struct TS3VirtualServerCreationParams
with the creation parameters for this virtual server.
flags
Defines if the server password is passed as plaintext or already encrypted. If already encrypted, this is the password retrieved via the server variable VIRTUALSERVER_PASSWORD
, which is returned as encrypted password. In this case you would specify the password on server creation as already encrypted to avoid the server encrypting it a second time.
enum VirtualServerCreateFlags{ VIRTUALSERVER_CREATE_FLAG_NONE = 0x0000, VIRTUALSERVER_CREATE_FLAG_PASSWORDS_ENCRYPTED = 0x0001, };
result
Address to be filled with the created virtual server ID.
Returns ERROR_ok
on success, otherwise an error code as defined in public_errors.h
.