Retrieve and store information

The Server Lib stores various pieces of information, which is made available to the custom server. This chapter covers how to query and store data in the Server Lib.

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

Client information

Query client information

Information about the clients currently connected to this virtual server can be retrieved and modified. To query client related information, use one of the following functions. The client is identified by the parameter clientID. The parameter flag is defined by the enum ClientProperties.

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

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

Parameters

  • serverID

    The ID of the virtual server on which the client property is queried.

  • clientID

    ID of the client whose property is queried.

  • flag

    Client propery to query, see below.

  • result

    Address of a variable that receives the result value as int or string, depending on which function is used. In case of a string, memory must be released using ts3server_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

  • CLIENT_VERSION

    Application version used by this client.

  • CLIENT_PLATFORM

    Operating system used by this client.

  • CLIENT_FLAG_TALKING

    Set when the client is currently talking. 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.

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

  • CLIENT_OUTPUT_HARDWARE

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

  • 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 available to client, not propagated to the server.

  • CLIENT_IDLE_TIME

    Time the client has been idle.

  • CLIENT_TYPE

    Indicates if the given client is a normal TeamSpeak 3 client or a connection established by the ServerQuery application.

  • CLIENT_DEFAULT_CHANNEL

    CLIENT_DEFAULT_CHANNEL_PASSWORD

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

  • CLIENT_META_DATA

    Not used by TeamSpeak 3, offers free storage for SDK users.

  • CLIENT_IS_MUTED

    Indicates a client has been locally muted with ts3server_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: Query nickname of client with ID 123:

unsigned int error;
anyID clientID = 123;  /* Client ID in our example */
char* nickname;

if((error = ts3server_getClientVariableAsString(serverID, clientID, CLIENT_NICKNAME, &nickname)) != ERROR_ok) {
    printf("Error querying client nickname: %d\n", error);
    return;
}

printf("Client nickname is: %s\n", nickname);
ts3server_freeMemory(nickname);

Setting client information

Client information can be modified with

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

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

Parameters

  • serverID

    ID of the virtual server on which the client property should be changed.

  • clientID

    ID of the client whose property should be 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]Important

After modifying one or more client variables, you must flush the changes.

unsigned int ts3server_flushClientVariable(serverID,  
 clientID); 
uint64 serverID;
anyID clientID;
 

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

For example, to change the nickname of the client with ID 55 to “Joe”:

anyID clientID = 55;  /* Client ID in our example */

/* Modifiy data */
if(ts3server_setClientVariableAsString(serverID, clientID, CLIENT_NICKNAME, "Joe") != ERROR_ok) {
    printf("Error setting client nickname\n");
    return;
}

/* Flush changes
if(ts3server_flushClientVariable(serverID, clientID) != ERROR_ok) {
    printf("Error flushing client variable\n");
}

Example for applying two changes:

anyID clientID = 66;  /* Client ID in our example */

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

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

/* Flush changes */
if(ts3server_flushClientVariable(scHandlerID, clientID) != ERROR_ok) {
    printf("Error flushing client variable");
}

Whisper lists

A client with a whisper list set can talk to the specified clients and channels. 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 ts3server_setClientWhisperList(serverID,  
 clID,  
 channelID,  
 clientID); 
uint64 serverID;
anyID clID;
const uint64* channelID;
const anyID* clientID;
 

Parameters

  • serverID

    ID of the virtual server on which the whisper list is set.

  • clID

    ID of the client whose whisper list is set.

  • channelID

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

    Pass NULL for an empty list.

  • clientID

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

    Pass NULL for an empty list.

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