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`)`; |

`uint64 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`)`; |

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

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

`uint64 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_OUTPUTONLY_MUTED         //automatically up-to-date for any client "in view", this clients
                                      //headphones/speakers only 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 users.

- `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.

  Note: You should query this flag for the own client using `ts3client_getClientSelfVariableAsInt`.

- `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 combined mute status of the clients playback and capture devices. Possible values are defined by the enum MuteOutputStatus. Always available for visible clients.

- `CLIENT_OUTPUTONLY_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`)`; |

`uint64 serverConnectionHandlerID`;
`ClientProperties flag`;
`int value`;

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

`uint64 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, |
| returnCode`)`; |
`uint64 serverConnectionHandlerID`; `const char* returnCode`;

The idea behind flushing is, one can modify multiple values by calling `ts3client_setClientVariableAsString` and `ts3client_setClientVariableAsInt` and then apply all changes in one step.

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, NULL) != 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, NULL) != 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, NULL) != 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`)`; |

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

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

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

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

`uint64 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, uint64 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`)`; |

`uint64 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. This event is also called everytime a client variable has been changed:

`void onUpdateClientEvent(` | serverConnectionHandlerID, |
| clientID, |
| invokerID, |
| invokerName, |
| invokerUniqueIdentifier`)`; |

`uint64 serverConnectionHandlerID`;
`anyID clientID`;
`anyID invokerID`;
`const char* invokerName`;
`const char* invokerUniqueIdentifier`;

Parameters

- `serverConnectionHandlerID`

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

- `clientID`

  ID of the client whose variables are now available or have changed.

- `invokerID`

  ID of the client who edited this clients variables.

- `invokerName`

  Nickname of the client who edited this clients variables.

- `invokerUniqueIdentifier`

  Unique ID of the client who edited this clients variables.

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 standard 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`)`; |

`uint64 serverConnectionHandlerID`;
`anyID clientID`;
`const uint64* 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`

  Array of channel IDs, terminated with 0. These channels will be added to the whisper list.

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

- `targetClientIDArray`

  Array of client IDs, terminated with 0. 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).

To control which client is allowed to whisper to own client, the Client Lib implements an internal whisper whitelist mechanism. When a client recieves a whisper while the whispering client has not yet been added to the whisper allow list, the receiving client gets the following event. Note that whisper voice data is not received until the sending client is added to the receivers whisper allow list.

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

`uint64 serverConnectionHandlerID`;
`anyID clientID`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the event occured.

- `clientID`

  ID of the whispering client.

The receiving client can decide to allow whispering from the sender and add the sending client to the whisper allow list by calling `ts3client_allowWhispersFrom`. If the sender is not added by the receiving client, this event persists being called but no voice data is transmitted to the receiving client.

To add a client to the whisper allow list:

`unsigned int ts3client_allowWhispersFrom(` | serverConnectionHandlerID, |
| clID`)`; |

`uint64 serverConnectionHandlerID`;
`anyID clID`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the client should be added to the whisper allow list.

- `clID`

  ID of the client to be added to the whisper allow list.

To remove a client from the whisper allow list:

`unsigned int ts3client_removeFromAllowedWhispersFrom(` | serverConnectionHandlerID, |
| clID`)`; |

`uint64 serverConnectionHandlerID`;
`anyID clID`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the client should be removed from the whisper allow list.

- `clID`

  ID of the client to be removed from the whisper allow list.

It won't have bad sideeffects if the same client ID is added to the whisper allow list multiple times.

Query available servers, channels and clients |  | Channel information