Managing clients

While in a traditional TeamSpeak setup, clients are moving themselves by joining channels, and clients can request to move other clients, the server is also able to perform these actions using the functions described in this chapter.

List clients

A list of all clients currently online on the specified virtual server can be queried with

unsigned int ts3server_getClientList(uint64 serverID, anyID **result)

get a list of all clients connected to a server

Parameters:

  • serverID – specifies the server on which to get the list of clients

  • result – address of a variable to receive the zero terminated list of clients, like {1, 2, 50, …, 0} Memory is allocated by the server library and caller must free the array using ts3server_freeMemory

Returns:

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

To get a list of all clients currently in the specified channel

unsigned int ts3server_getChannelClientList(uint64 serverID, uint64 channelID, anyID **result)

get list of clients in a channel

Parameters:

  • serverID – the server on which the channel is located

  • channelID – the channel of which to get the list of clients

  • result – address of a variable to receive a zero terminated array of client ids in the channel. Like {3, 5, 39, …, 0} Memory is allocated by the server library and caller must free the array using ts3server_freeMemory

Returns:

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

Moving clients

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(uint64 serverID, uint64 newChannelID, const anyID *clientIDArray)

Move one or more clients to a different channel.

Parameters:

  • serverID – specifies the server the client is connected to

  • newChannelID – the id of the channel to move the client(s) to

  • clientIDArray – zero terminated array of client ids to move. Like {4, 9, …, 0}

Returns:

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

Example

Example to move a single client to another channel:

 1anyID clientIDArray[2];  /* One client plus terminating zero as end-marker */
 2uint64 newChannelID;
 3unsigned int error;
 4
 5clientIDArray[0] = clientID;  /* Client to move */
 6clientIDArray[1] = 0;  /* End marker */
 7
 8if ((error = ts3server_clientMove(serverID, newChannelID, channelIDArray)) != ERROR_ok) {
 9    /* Handle error */
10    return;
11}
12
13/* Client moved successfully */

Kicking Clients

In additions to the client side feature, the server can also kick clients from the server itself using

unsigned int ts3server_clientsKickFromServer(uint64 serverID, const anyID *clientIDArray, const char *kickReason, int failOnClientError)

kick one or more clients from the server, terminating their connection.

Parameters:

  • serverID – the server the client(s) are connected to

  • clientIDArray – zero terminated array of client ids to kick. Like {4, 3, 12, …, 0}

  • kickReason – utf8 encoded c string describing the reason for the kick. Pass an empty string if unused.

  • failOnClientError – boolean flag. If 1 the function will fail if clients to be kicked are not on the server.

Returns:

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

Client information

Information about the clients currently connected to the virtual server can be retrieved and modified.

Available variables are listed in the ClientProperties enum.

Note

The server always has all the information about all clients as long as they are connected to the server.

Limitations regarding availability mentioned for the variables are thus of no concern for the server.

Query client information

To query client related information, use one of the following functions depending on the type of the variable you are going to query.

unsigned int ts3server_getClientVariableAsInt(uint64 serverID, anyID clientID, enum ClientProperties flag, int *result)

get the value of a client variable as integer.

Not all variables are available as integer, some are only available as string or unsigned 64 bit integer.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • result – address of a variable to receive the value of the variable queried.

Returns:

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

unsigned int ts3server_getClientVariableAsUInt64(uint64 serverID, anyID clientID, enum ClientProperties flag, uint64 *result)

get the value of a client variable as unsigned 64 bit integer.

Not all variables are available as unsigned 64 bit integer, some are only available as string or integer.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • result – address of a variable to receive the value of the variable queried.

Returns:

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

unsigned int ts3server_getClientVariableAsString(uint64 serverID, anyID clientID, enum ClientProperties flag, char **result)

get the value of the client variable as string

Not all variables are available as string, some are only available as unsigned 64 bit integer or integer.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • result – address of a variable to receive the value of the variable queried.

Returns:

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

Example

Query nickname of client with ID 123:

 1unsigned int error;
 2anyID clientID = 123;  /* Client ID in our example */
 3char* nickname;
 4
 5if ((error = ts3server_getClientVariableAsString(serverID, clientID, CLIENT_NICKNAME, &nickname)) != ERROR_ok) {
 6    printf("Error querying client nickname: %d\n", error);
 7    return;
 8}
 9
10printf("Client nickname is: %s\n", nickname);
11ts3server_freeMemory(nickname);

Setting client information

Client information can be modified with

unsigned int ts3server_setClientVariableAsInt(uint64 serverID, anyID clientID, enum ClientProperties flag, int value)

set the value of a client variable.

Not all variables can be set as integer.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • value – the new value to set

Returns:

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

unsigned int ts3server_setClientVariableAsUInt64(uint64 serverID, anyID clientID, enum ClientProperties flag, uint64 value)

set the value of a client variable.

Not all variables can be set as unsigned 64 bit integer.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • value – the new value to set

Returns:

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

unsigned int ts3server_setClientVariableAsString(uint64 serverID, anyID clientID, enum ClientProperties flag, const char *value)

set the value of a client variable.

Not all variables can be set as string.

Parameters:

  • serverID – specifies the server the client is on

  • clientID – which client to query

  • flag – specifies which variable to retrieve. One of the values from the ClientProperties enum.

  • value – the new value to set

Returns:

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

Important

After modifying one or more client variables, you must flush the changes using ts3server_flushClientVariable().

The idea behind flushing is, one can modify multiple values by calling ts3server_setClientVariableAsString(), ts3server_setClientVariableAsInt() and ts3server_setClientVariableAsUInt64() for a client and then apply all changes in one step.

Examples

To change the nickname of the client with ID 55 to “Joe”:

 1anyID clientID = 55;  /* Client ID in our example */
 2
 3/* Modifiy data */
 4if (ts3server_setClientVariableAsString(serverID, clientID, CLIENT_NICKNAME, "Joe") != ERROR_ok) {
 5    printf("Error setting client nickname\n");
 6    return;
 7}
 8
 9/* Flush changes */
10if (ts3server_flushClientVariable(serverID, clientID) != ERROR_ok) {
11    printf("Error flushing client variable\n");
12}

Changing multiple variables is as simple as:

 1anyID clientID = 66;  /* Client ID in our example */
 2
 3/* Modify data 1 */
 4if (ts3server_setClientVariableAsString(serverID, clientID, CLIENT_NICKNAME, "bob") != ERROR_ok) {
 5    printf("Error setting nickname\n");
 6    return;
 7}
 8
 9/* Modify data 2 */
10if (ts3server_setClientVariableAsString(serverID, clientID, CLIENT_META_DATA, "some data") != ERROR_ok) {
11    printf("Error setting meta data\n");
12    return;
13}
14
15/* Flush changes */
16if (ts3server_flushClientVariable(serverID, clientID) != ERROR_ok) {
17    printf("Error flushing client variable");
18}