Client information

Once connected to a server information about connected clients as well as your own client are available to be queried. Some information of your own client can also be modified.

Available variables are listed in the ClientProperties enum.

Requesting updated information

As the Client Lib cannot have all information for all users available all the time, the latest data for a given client can be requested from the server using

unsigned int ts3client_requestClientVariables(uint64 serverConnectionHandlerID, anyID clientID, const char *returnCode)

Ask the server to provide additional request only variables for a client.

You will receive an onUpdateClientEvent callback when the data is available to you.

Parameters:

  • serverConnectionHandlerID – the connection handler on which the client is located

  • clientID – the client for which to receive the client variables

  • returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

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

Note

To avoid flooding the server, a mandatory delay of one second is enforced before this function can be called again for the same client id.

After requesting the information, the following callback is called. This callback is also called every time a client variable has been changed.

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onUpdateClientEvent)(uint64 serverConnectionHandlerID, anyID clientID, anyID invokerID, const char *invokerName, const char *invokerUniqueIdentifier)

called whenever a change for a client is received from the server.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param clientID:

specifies the client for which variables have changed or are now available

Param invokerID:

the source client that caused the update

Param invokerName:

utf8 encoded c string containing the display name of the client causing the update

Param invokerUniqueIdentifier:

utf8 encoded c string containing the public identity of the client causing the update

The event does not carry the information itself, but now the Client Lib guarantees to have the client information available, which can be subsequently queried using ts3client_getClientVariableAsInt(), ts3client_getClientVariableAsUInt64() and ts3client_getClientVariableAsString() as described below.

Query client information

To query client related information, use one of the following functions.

unsigned int ts3client_getClientVariableAsInt(uint64 serverConnectionHandlerID, anyID clientID, size_t flag, int *result)

Retrieve the value of a variable from a client as integer.

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

Parameters:

  • serverConnectionHandlerID – connection handler on which the client is located

  • clientID – for which client to retrieve the value

  • flag – specifies which variable to receive. One of the values from the ClientProperties or ClientPropertiesRare enums

  • result – address of a variable to receive the value on success

Returns:

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

unsigned int ts3client_getClientVariableAsUInt64(uint64 serverConnectionHandlerID, anyID clientID, size_t flag, uint64 *result)

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

Not all variables are available as integer. Some are only available as string or integer.

Parameters:

  • serverConnectionHandlerID – connection handler on which the client is located

  • clientID – for which client to retrieve the value

  • flag – specifies which variable to receive. One of the values from the ClientProperties or ClientPropertiesRare enums

  • result – address of a variable to receive the value on success

Returns:

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

unsigned int ts3client_getClientVariableAsString(uint64 serverConnectionHandlerID, anyID clientID, size_t flag, char **result)

Retrieve the value of a variable from a client as string.

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

Parameters:

  • serverConnectionHandlerID – connection handler on which the client is located

  • clientID – for which client to retrieve the value

  • flag – specifies which variable to receive. One of the values from the ClientProperties or ClientPropertiesRare enums

  • result – address of a variable to receive the value on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Own client

Once a connection to a TeamSpeak 3 server has been established, a client ID is assigned by the server. This ID can be queried with

unsigned int ts3client_getClientID(uint64 serverConnectionHandlerID, anyID *result)

get your own client id on a server

Parameters:

  • serverConnectionHandlerID – the connection handler on which to retrieve your own client id

  • result – address of a variable to receive your client id on success

Returns:

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

In addition to the functions discussed above, the client lib offers convenience functions to query the own client information that does not require a clientID parameter to be specified. Various information related about the own client can be checked with:

unsigned int ts3client_getClientSelfVariableAsInt(uint64 serverConnectionHandlerID, size_t flag, int *result)

Retrieve value of a variable of your own client as an integer.

Not all variables are available as integer. Some are only available as string. NOTE: Not all variables are available using this function, some are only available using ts3client_getClientVariableAsInt

Parameters:

  • serverConnectionHandlerID – connection handler on which to retrieve information

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

  • result – address of a variable to receive the value on success

Returns:

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

unsigned int ts3client_getClientSelfVariableAsString(uint64 serverConnectionHandlerID, size_t flag, char **result)

Retrieve value of a variable of your own client as string.

Not all variables are available as integer. Some are only available as integer. NOTE: Not all variables are available using this function, some are only available using ts3client_getClientVariableAsString

Parameters:

  • serverConnectionHandlerID – connection handler on which to retrieve information

  • flag – specifies which variable to receive. One of the values from the ClientProperties or ClientPropertiesRare enums

  • result – address of a variable to receive the value on success. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Note

Not all variables are available using these functions. Some will require using the functions for any client discussed above.

Examples

Example 1: Query client nickname

1char* nickname;
2
3if (ts3client_getClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, &nickname) == ERROR_ok) {
4    printf("My nickname is: %s\n", s);
5    ts3client_freeMemory(s);
6}

Example 2: Check if own client is currently talking (to be exact: sending voice data)

 1int talking;
 2
 3if (ts3client_getClientSelfVariableAsInt(scHandlerID, CLIENT_FLAG_TALKING, &talking) == ERROR_ok) {
 4    switch (talking) {
 5        case STATUS_TALKING:
 6            // I am currently talking
 7            break;
 8        case STATUS_NOT_TALKING:
 9            // I am currently not talking
10            break;
11        case STATUS_TALKING_WHILE_DISABLED:
12            // I am talking while microphone is disabled
13            break;
14        default:
15            printf("Invalid value for CLIENT_FLAG_TALKING\n");
16    }
17}

Setting client information

Information related to the own client can be modified with

unsigned int ts3client_setClientSelfVariableAsInt(uint64 serverConnectionHandlerID, size_t flag, int value)

Change the value of an integer variable on your own client.

After having changed all variables desired, call ts3client_flushClientSelfUpdates to publish the changes to the server Not all variables can be changed, many are read only.

Parameters:

  • serverConnectionHandlerID – the connection handler on which to set the value

  • flag – specifies which variable to change. One of the values from the ClientProperties or ClientPropertiesRare enums

  • value – the new value to set

Returns:

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

unsigned int ts3client_setClientSelfVariableAsString(uint64 serverConnectionHandlerID, size_t flag, const char *value)

Change the value of a string variable on your own client.

After having changed all variables desired, call ts3client_flushClientSelfUpdates to publish the changes to the server Not all variables can be changed, many are read only.

Parameters:

  • serverConnectionHandlerID – the connection handler on which to set the value

  • flag – specifies which variable to change. One of the values from the ClientProperties or ClientPropertiesRare enums

  • 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. Flushing ensures the changes are sent to the TeamSpeak 3 server.

unsigned int ts3client_flushClientSelfUpdates(uint64 serverConnectionHandlerID, const char *returnCode)

Send changes to the local client to the server.

Publish changes previously set using ts3client_setClientSelfVariableAsInt and ts3client_setClientSelfVariableAsString on the connection handler.

Parameters:

  • serverConnectionHandlerID – connection handler on which to publish changes

  • returnCode – a c string to identify this request in callbacks. Pass an empty string if unused.

Returns:

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

The idea behind flushing is, one can modify multiple values by calling ts3client_setClientSelfVariableAsString() and ts3client_setClientSelfVariableAsInt() and then apply all changes in one step.

Examples

For example, to change the own nickname:

 1/* Modify data */
 2if (ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, "Joe") != ERROR_ok) {
 3    printf("Error setting client variable\n");
 4    return;
 5}
 6
 7/* Flush changes */
 8if (ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
 9    printf("Error flushing client updates");
10}

Example for doing two changes:

 1/* Modify data 1 */
 2if (ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, "SDK User") != ERROR_ok) {
 3    printf("Error setting nickname\n");
 4    return;
 5}
 6
 7/* Modify data 2 */
 8if (ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_META_DATA, "Lunch") != ERROR_ok) {
 9    printf("Error setting meta data\n");
10    return;
11}
12
13/* Flush changes */
14if (ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
15    printf("Error flushing client updates");
16}

Example to mute and unmute the microphone:

 1unsigned int error;
 2bool shouldTalk;
 3
 4shouldTalk = isPushToTalkButtonPressed();  // Your key detection implementation
 5if((error = ts3client_setClientSelfVariableAsInt(scHandlerID, CLIENT_INPUT_DEACTIVATED,
 6                                                 shouldTalk ? INPUT_ACTIVE : INPUT_DEACTIVATED)) != ERROR_ok) {
 7    char* errorMsg;
 8    if(ts3client_getErrorMessage(error, &errorMsg) != ERROR_ok) {
 9        printf("Error toggling push-to-talk: %s\n", errorMsg);
10    ts3client_freeMemory(errorMsg);
11    }
12    return;
13}
14
15if(ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
16    char* errorMsg;
17    if(ts3client_getErrorMessage(error, &errorMsg) != ERROR_ok) {
18        printf("Error flushing after toggling push-to-talk: %s\n", errorMsg);
19    ts3client_freeMemory(errorMsg);
20    }
21}

See the FAQ section for further details on implementing Push-To-Talk.