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.
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);
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 | |||||
---|---|---|---|---|---|---|
After modifying one or more client variables, you must flush the changes.
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"); }
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
.