Advanced channel creation

There is an alternative API available for channel creation, similar to the alternative virtual server creation API. The idea is to create a TS3ChannelCreationParams structure, query the attached TS3Variables structure, 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.

Obtain a channel creation structure

First we need to create a TS3ChannelCreationParams struct using

unsigned int ts3server_makeChannelCreationParams(struct TS3ChannelCreationParams **result)

Create a structure that defines channel properties for use with ts3server_createChannel.

Parameters:

  • result – address of a variable to receive a pointer to the structure. Pointer must not be freed! After receiving the structure pointer, it must be filled using ts3server_setChannelCreationParams

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 channel exists. The server lib will take care of cleaning up the structure at an appropriate time.

Once we have a TS3ChannelCreationParams struct for this channel, we can start to fill it in two steps. Step 1 is setting the essential data, step 2 is setting additional data.

Setting basic channel properties

Essential parameters are channel parent ID and channel ID. These are specified 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

Setting additional channel properties

After setting the essential parameters, we can set additional channel parameters.

To do so we first need to retrieve the TS3Variables for this channel and fill it.

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 TS3Variables we can set them by calling ts3server_setVariableAsInt(), ts3server_setVariableAsUInt64() or ts3server_setVariableAsString(). You can also get the current value using ts3server_getVariableAsInt(), ts3server_getVariableAsUInt64() and ts3server_getVariableAsString().

Actually create the channel

Finally, after setting up channel parameters, create the channel in one step with

unsigned int ts3server_createChannel(uint64 serverID, struct TS3ChannelCreationParams *channelCreationParams, enum ChannelCreateFlags flags, uint64 *result)

create a new channel on an existing virtual server.

Parameters:

  • serverID – the server on which to create the channel.

  • channelCreationParams – defines channel properties. Address of the structure obtained by calling ts3server_makeChannelCreationParams Must have been filled using ts3server_setChannelCreationParams before this call.

  • flags – defines how certain information is presented in the channelCreationParams. Combination of the values from the ChannelCreateFlags enum

  • result – address of a variable to receive the channel id of the newly created channel.

Returns:

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