Advanced virtual server creation

In addition to the previously mentioned way to create a virtual server using ts3server_createVirtualServer(), there is an alternative way to create a virtual server. The advantage of this method is the possibility to restore the complete channel structure upon 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.

Create server structure pointer

First, a TS3VirtualServerCreationParams has to be created, which will be filled with essential and optional server parameters. This will eventually contain the entire virtual server structure and is used to create and start the virtual server.

Create a new virtual server parameter structure using

unsigned int ts3server_makeVirtualServerCreationParams(struct TS3VirtualServerCreationParams **result)

Creates a structure to define an entire virtual server including the channel layout for server creation for use with ts3server_createVirtualServer2.

This is the first function to call when using the ts3server_createVirtualServer2 meachanism of creating virtual servers in one go, including all of their channels. After receiving the structure using this function, you need to call ts3server_setVirtualServerCreationParams to set basic configuration for this virtual server. Once that is done you can set additional parameters using ts3server_getVirtualServerCreationParamsVariables and ts3server_setVariableAsInt, ts3server_setVariableAsUInt64 or ts3server_setVariableAsString

Parameters:

  • result – address of a variable to receive a pointer to a structure defining the virtual server. This must be filled using ts3server_setVirtualServerCreationParams after this. Pointer must not be freed by caller.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Important

Do not free or dispose of the structure, it must be valid as long as the virtual server exists. The server lib will take care of cleaning up the structure at an appropriate time.

Set essential server properties

Once the TS3VirtualServerCreationParams structure 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, maximum number of clients, number of channels we want to start the server with and the virtual server ID.

To set these essential parameters call the function

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

Set mandatory server creation properties for server creation using ts3server_createVirtualServer2.

This call is mandatory after calling ts3server_makeVirtualServerCreationParams when using ts3server_createVirtualServer2 and sets the basic information to create a virtual server. After this call you can optionally set other variables by calling ts3server_getVirtualServerCreationParamsVariables after this.

Parameters:

  • virtualServerCreationParams – pointer to a struct of creation parameters obtained by calling ts3server_makeVirtualServerCreationParams

  • serverPort – the UDP port to listen for client connections on

  • serverIp – comma separated list of IP address(es) to listen for client connections on. IPv4 and IPv6 addresses are supported.

  • serverKeyPair – unique key for encryption. Pass an empty string when originally creating a new server, query the generated encryption key with ts3server_getVirtualServerKeyPair, store it and use it on subsequent start ups.

  • serverMaxClients – maximum number of clients that can be connected simultaneously at any given time

  • channelCount – the amount of channels this server will have after creation. You must call ts3server_getVirtualServerCreationParamsChannelCreationParams with this virtualServerCreationParams exactly this many times.

  • serverID – the id this virtual server will have when created. server id must be unique during life time of the server library.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Query and set optional server properties

After essential virtual server parameters have been defined with ts3server_setVirtualServerCreationParams(), additional parameters can be set. For that, we first need to get a TS3Variables from the TS3VirtualServerCreationParams, in which the additional paramters will be written using the functions ts3server_setVariableAsInt(), ts3server_setVariableAsUInt64() and ts3server_setVariableAsString().

To receive a pointer to a TS3Variables structure call

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

create struct to define optional server settings for server creation with ts3server_createVirtualServer2

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Once you have a pointer to a valid TS3Variables structure, 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.

Query variables

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

get the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as integer. Some are only available as string or unsigned 64 bit integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

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

get the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as unsigned 64 bit integer. Some are only available as string or integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

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

get the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as string. Some are only available as unsigned 64 bit integer or integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Set variables

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

set the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as integer. Some are only available as string or unsigned 64 bit integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

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

set the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as unsigned 64 bit integer. Some are only available as string or integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

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

set the value of a property of a server or channel when using ts3server_createVirtualServer2 or ts3server_createChannel

Not all properties are available as string. Some are only available as unsigned 64 bit integer or integer.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Example

The following will set the virtual server name of the server to be created later to “My Server”

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

Initialize the channel tree

After setting global virtual server parameters we are ready to initialize the channel tree.

Note

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

For each channel you need to get a TS3ChannelCreationParams and fill it with the desired channel parameters, including the channel ID.

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

Used to specify channels to create during advanced server creation using ts3server_createVirtualServer2.

Call this function exactly as often as you indicated channels to be created in the ts3server_setVirtualServerCreationParams call. Once you have received the struct you must set the details using ts3server_setChannelCreationParams and can optionally set additional parameters using ts3server_getChannelCreationParamsVariables to get a structure to fill using ts3server_setVariableAsInt, ts3server_setVariableAsString, ts3server_setVariableAsUInt64

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Important

These structures are used by the server library and must remain valid for the life time of the virtual server we are creating. Do not free or dispose of these structures.

Set essential channel properties

Once we have a TS3ChannelCreationParams pointer 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, which define where the channel will exist. Set them using

unsigned int ts3server_setChannelCreationParams(struct TS3ChannelCreationParams *channelCreationParams, uint64 channelParentID, uint64 channelID)

Specify mandatory details of a channel to be created at server creation using ts3server_createVirtualServer2.

Must be called after ts3server_getVirtualServerCreationParamsChannelCreationParams to set basic properties of a channel. After this call you may set additional channel properties by calling ts3server_getChannelCreationParamsVariables and ts3server_setVariableAsInt, ts3server_setVariableAsUInt64 or ts3server_setVariableAsString

Parameters:

  • channelCreationParams – defines the channel for which we set basic properties. Obtained by calling ts3server_getVirtualServerCreationParamsChannelCreationParams

  • channelParentID – the id of the channel that this channel is a sub channel of. Pass 0 to make this channel a root channel.

  • channelID – the id this channel should have. Pass 0 to have the server lib assign a free ID. This is used to identify the channel in other calls to the client and server library. Must be unique across all virtual servers during the lifetime of the server library.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Set and query optional channel properties

After setting the essential parameters, we can set optional parameters in a similar way as we did for the virtual server itself.

Retrieve a TS3Variables pointer for this channel using

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

Allows settings optional channel properties for channels to be created either at server creation using ts3server_createVirtualServer2 or using ts3server_createChannel.

Parameters:
Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Once we have the structure use the previously described functions ts3server_setVariableAsInt(), ts3server_setVariableAsUInt64() and ts3server_setVariableAsString() to modify the properties. You can use ts3server_getVariableAsInt(), ts3server_getVariableAsUInt64() and ts3server_getVariableAsString() to query current properties for the channel.

Create the virtual server and channels

Once we have defined the virtual server, and set up all the channels needed as described before, we can finally go ahead and actually create the virtual server and all the channels as specified using

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

Create an entire server structure in a single call. Useful for restoring an entire virtual server including channels including their ids after storing them on shutdown. See the SDK documentation for more in depth information.

This requires a few other calls to be made in advance. First you need to call ts3server_makeVirtualServerCreationParams to get a TS3VirtualServerCreationParams struct that then needs to be filled via ts3server_setVirtualServerCreationParams. You can then use ts3server_getVirtualServerCreationParamsVariables to set other server settings and use ts3server_getVirtualServerCreationParamsChannelCreationParams to specify channels to create using ts3server_setChannelCreationParams.

Parameters:

  • virtualServerCreationParams – pointer to the server parameters obtained by calling ts3server_makeVirtualServerCreationParams. These must have been filled using ts3server_setVirtualServerCreationParams before calling this function.

  • flags – defines how certain information is present in the virtualServerCreationParams. Combination of the values from the VirtualServerCreateFlags enum

  • result – address of a variable to receive the created servers id. This is used in other calls to the server library to identify this server.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Note

Before this function is called, neither the server nor any of the channels actually exist anywhere. We merely described how they should look like and where the channels are. You cannot use any functions that require things to actually exist before this function was successfully called