Retrieve and store information

## Retrieve and store information

The Client Lib remembers a lot of information which have been passed through previously. The data is available to be queried by a client for convinience, so the interface code doesn't need to store the same information as well. The client can in many cases also modify the stored information for further processing by the server.

All strings passed to and from the Client Lib need to be encoded in UTF-8 format.

### Client information

#### Information related to own client

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

`unsigned int ts3client_getClientID(` | serverConnectionHandlerID, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`anyID* result`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which we are querying the own client ID.

- `result`

  Address of a variable that receives the client ID. Client IDs start with the value 1.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

Various information related about the own client can be checked with:

`unsigned int ts3client_getClientSelfVariableAsInt(` | serverConnectionHandlerID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`ClientProperties flag`;
`int* result`;

`unsigned int ts3client_getClientSelfVariableAsString(` | serverConnectionHandlerID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`ClientProperties flag`;
`char** result`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the information for the own client is requested.

- `flag`

  Client propery to query, see below.

- `result`

  Address of a variable which receives the result value as int or string, depending on which function is used. In case of a string, memory must be released using `ts3client_freeMemory`, unless an error occured.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`. For the string version: If an error has occured, the result string is uninitialized and must not be released.

The parameter `flag` specifies the type of queried information. It is defined by the enum ClientProperties:

    enum ClientProperties {
      CLIENT_UNIQUE_IDENTIFIER = 0,   //automatically up-to-date for any client "in view", can be used
                                      //to identify this particular client installation
      CLIENT_NICKNAME,                //automatically up-to-date for any client "in view"
      CLIENT_VERSION,                 //for other clients than ourself, this needs to be requested
                                      //(=> requestClientVariables)
      CLIENT_PLATFORM,                //for other clients than ourself, this needs to be requested
                                      //(=> requestClientVariables)
      CLIENT_FLAG_TALKING,            //automatically up-to-date for any client that can be heard
                                      //(in room / whisper)
      CLIENT_INPUT_MUTED,             //automatically up-to-date for any client "in view", this clients
                                      //microphone mute status
      CLIENT_OUTPUT_MUTED,            //automatically up-to-date for any client "in view", this clients
                                      //headphones/speakers mute status
      CLIENT_INPUT_HARDWARE,          //automatically up-to-date for any client "in view", this clients
                                      //microphone hardware status (is the capture device opened?)
      CLIENT_OUTPUT_HARDWARE,         //automatically up-to-date for any client "in view", this clients
                                      //headphone/speakers hardware status (is the playback device opened?)
      CLIENT_INPUT_DEACTIVATED,       //only usable for ourself, not propagated to the network
      CLIENT_IDLE_TIME,               //internal use
      CLIENT_DEFAULT_CHANNEL,         //only usable for ourself, the default channel we used to connect
                                      //on our last connection attempt
      CLIENT_DEFAULT_CHANNEL_PASSWORD,//internal use
      CLIENT_SERVER_PASSWORD,         //internal use
      CLIENT_META_DATA,               //automatically up-to-date for any client "in view", not used by
                                      //TeamSpeak, free storage for sdk users
      CLIENT_IS_MUTED,                //only make sense on the client side locally, "1" if this client is
                                      //currently muted by us, "0" if he is not
      CLIENT_IS_RECORDING,            //automatically up-to-date for any client "in view"
      CLIENT_VOLUME_MODIFICATOR,      //internal use
      CLIENT_ENDMARKER,
    };

- `CLIENT_UNIQUE_IDENTIFIER`

  String: Unique ID for this client. Stays the same after restarting the application, so you can use this to identify individual user.

- `CLIENT_NICKNAME`

  Nickname used by the client. This value is always automatically updated for visible clients.

- `CLIENT_VERSION`

  Application version used by this client. Needs to be requested with `ts3client_requestClientVariables` unless called on own client.

- `CLIENT_PLATFORM`

  Operating system used by this client. Needs to be requested with `ts3client_requestClientVariables` unless called on own client.

- `CLIENT_FLAG_TALKING`

  Set when the client is currently sending voice data to the server. Always available for visible clients.

- `CLIENT_INPUT_MUTED`

  Indicates the mute status of the clients capture device. Possible values are defined by the enum MuteInputStatus. Always available for visible clients.

- `CLIENT_OUTPUT_MUTED`

  Indicates the mute status of the clients playback device. Possible values are defined by the enum MuteOutputStatus. Always available for visible clients.

- `CLIENT_INPUT_HARDWARE`

  Set if the clients capture device is not available. Possible values are defined by the enum HardwareInputStatus. Always available for visible clients.

- `CLIENT_OUTPUT_HARDWARE`

  Set if the clients playback device is not available. Possible values are defined by the enum HardwareOutputStatus. Always available for visible clients.

- `CLIENT_INPUT_DEACTIVATED`

  Set when the capture device has been deactivated as used in Push-To-Talk. Possible values are defined by the enum InputDeactivationStatus. Only used for the own clients and not available for other clients as it doesn't get propagated to the server.

- `CLIENT_IDLE_TIME`

  Time the client has been idle. Needs to be requested with `ts3client_requestClientVariables`.

- `CLIENT_DEFAULT_CHANNEL`

  `CLIENT_DEFAULT_CHANNEL_PASSWORD`

  Default channel name and password used in the last `ts3client_startConnection` call. Only available for own client.

- `CLIENT_META_DATA`

  Not used by TeamSpeak 3, offers free storage for SDK users. Always available for visible clients.

- `CLIENT_IS_MUTED`

  Indicates a client has been locally muted with `ts3client_requestMuteClients`. Client-side only.

- `CLIENT_IS_RECORDING`

  Indicates a client is currently recording all voice data in his channel.

- `CLIENT_VOLUME_MODIFICATOR`

  The client volume modifier set by `ts3client_setClientVolumeModifier`.

Generally all types of information can be retrieved as both string or integer. However, in most cases the expected data type is obvious, like querying `CLIENT_NICKNAME` will clearly require to store the result as string.

Example 1: Query client nickname

    char* nickname;

    if(ts3client_getClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, &nickname) == ERROR_ok) {
        printf("My nickname is: %s\n", s);
        ts3client_freeMemory(s);
    }

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

    int talking;

    if(ts3client_getClientSelfVariableAsInt(scHandlerID, CLIENT_FLAG_TALKING, &talking) == ERROR_ok) {
        switch(talking) {
            case STATUS_TALKING:
                // I am currently talking
    	    break;
    	case STATUS_NOT_TALKING:
    	    // I am currently not talking
    	    break;
    	case STATUS_TALKING_WHILE_DISABLED:
    	    // I am talking while microphone is disabled
    	    break;
    	default:
    	    printf("Invalid value for CLIENT_FLAG_TALKING\n");
        }
    }

Information related to the own client can be modified with

`unsigned int ts3client_setClientSelfVariableAsInt(` | serverConnectionHandlerID, |
| flag, |
| value`)`; |

`anyID serverConnectionHandlerID`;
`ClientProperties flag`;
`int value`;

`unsigned int ts3client_setClientSelfVariableAsString(` | serverConnectionHandlerID, |
| flag, |
| value`)`; |

`anyID serverConnectionHandlerID`;
`ClientProperties flag`;
`const char* value`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the information for the own client is changed.

- `flag`

  Client propery to query, see above.

- `value`

  Value the client property should be changed to.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

| 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(` | serverConnectionHandlerID`)`; |
`anyID serverConnectionHandlerID`;

For example, to change the own nickname:

    /* Modify data */
    if(ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, "Joe") != ERROR_ok) {
        printf("Error setting client variable\n");
        return;
    }

    /* Flush changes */
    if(ts3client_flushClientSelfUpdates(scHandlerID) != ERROR_ok) {
        printf("Error flushing client updates");
    }

Example for doing two changes:

    /* Modify data 1 */
    if(ts3client_setClientSelfVariableAsInt(scHandlerID, CLIENT_AWAY, AWAY_ZZZ) != ERROR_ok) {
        printf("Error setting away mode\n");
        return;
    }

    /* Modify data 2 */
    if(ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_AWAY_MESSAGE, "Lunch") != ERROR_ok) {
        printf("Error setting away message\n");
        return;
    }

    /* Flush changes */
    if(ts3client_flushClientSelfUpdates(scHandlerID) != ERROR_ok) {
        printf("Error flushing client updates");
    }

Example to mute and unmute the microphone:

    unsigned int error;
    bool shouldTalk;

    shouldTalk = isPushToTalkButtonPressed();  // Your key detection implementation
    if((error = ts3client_setClientSelfVariableAsInt(scHandlerID, CLIENT_INPUT_DEACTIVATED,
                                                     shouldTalk ? INPUT_ACTIVE : INPUT_DEACTIVATED)) != ERROR_ok) {
        char* errorMsg;
        if(ts3client_getErrorMessage(error, &errorMsg) != ERROR_ok) {
            printf("Error toggling push-to-talk: %s\n", errorMsg);
    	ts3client_freeMemory(errorMsg);
        }
        return;
    }

    if(ts3client_flushClientSelfUpdates(scHandlerID) != ERROR_ok) {
        char* errorMsg;
        if(ts3client_getErrorMessage(error, &errorMsg) != ERROR_ok) {
            printf("Error flushing after toggling push-to-talk: %s\n", errorMsg);
    	ts3client_freeMemory(errorMsg);
        }
    }

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

#### Information related to other clients

Information related to other clients can be retrieved in a similar way. Unlike own clients however, information cannot be modified.

To query client related information, use one of the following functions. The parameter `flag` is defined by the enum ClientProperties as shown above.

`unsigned int ts3client_getClientVariableAsInt(` | serverConnectionHandlerID, |
| clientID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`ClientProperties flag`;
`int* result`;

`unsigned int ts3client_getClientVariableAsString(` | serverConnectionHandlerID, |
| clientID, |
| flag, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`ClientProperties flag`;
`char** result`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the information for the specified client is requested.

- `clientID`

  ID of the client whose property is queried.

- `flag`

  Client propery to query, see above.

- `result`

  Address of a variable which receives the result value as int or string, depending on which function is used. In case of a string, memory must be released using `ts3client_freeMemory`, unless an error occured.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`. For the string version: If an error has occured, the result string is uninitialized and must not be released.

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 with:

`unsigned int ts3client_requestClientVariables(` | serverConnectionHandlerID, |
| clientID, |
| returnCode`)`; |

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`const char* returnCode`;

The function requires one second delay before calling it again on the same client ID to avoid flooding the server.

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the client variables are requested.

- `clientID`

  ID of the client whose variables are requested.

- `returnCode`

  See return code documentation. Pass NULL if you do not need this feature.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

After requesting the information, the following event is called:

`void onUpdateClientEvent(` | serverConnectionHandlerID, |
| clientID`)`; |

`anyID serverConnectionHandlerID`;
`anyID clientID`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the client variables are now available.

- `clientID`

  ID of the client whose variables are now available.

The event does not carry the information per se, but now the Client Lib guarantees to have the clients information available, which can be subsequently queried with `ts3client_getClientVariableAsInt` and `ts3client_getClientVariableAsString`.

#### Whisper lists

A client with a whisper list set can talk to the specified clients and channels bypassing the normal rule that voice is only transmitted to the current channel. Whisper lists can be defined for individual clients. A whisper list consists of an array of client IDs and/or an array of channel IDs.

`unsigned int ts3client_requestClientSetWhisperList(` | serverConnectionHandlerID, |
| clientID, |
| targetChannelIDArray, |
| targetClientIDArray, |
| returnCode`)`; |

`anyID serverConnectionHandlerID`;
`anyID clientID`;
`const anyID* targetChannelIDArray`;
`const anyID* targetClientIDArray`;
`const char* returnCode`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the clients whisper list is modified.

- `clientID`

  ID of the client whose whisper list is modified. If set to 0, the own client is modified (same as setting to own client ID).

- `targetChannelIDArray`

  NULL-terminated array of channel IDs. These channels will be added to the whisper list.

  To clear the list, pass NULL or an empty array.

- `targetClientIDArray`

  NULL-termianted array of client IDs. These clients will be added to the whisper list.

  To clear the list, pass NULL or an empty array.

- `returnCode`

  See return code documentation. Pass NULL if you do not need this feature.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`.

To disable the whisperlist for the given client, pass NULL to both `targetChannelIDArray` and `targetClientIDArray`. Careful: If you pass two empty arrays, whispering is not disabled but instead one would still be whispering to nobody (empty lists).

Query available servers, channels and clients |  | Channel information