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}