Server information

Server information
á	Retrieve and store information	á

Similar to querying client and channel data, server information can be checked with

`unsigned int ts3client_getServerVariableAsInt(`	`serverConnectionHandlerID`,	á
á	`flag`,	á
á	`result)`;	á

uint64 serverConnectionHandlerID;
VirtualServerProperties flag;
int* result;

`unsigned int ts3client_getServerVariableAsUInt64(`	`serverConnectionHandlerID`,	á
á	`flag`,	á
á	`result)`;	á

uint64 serverConnectionHandlerID;
VirtualServerProperties flag;
uint64* result;

`unsigned int ts3client_getServerVariableAsString(`	`serverConnectionHandlerID`,	á
á	`flag`,	á
á	`result)`;	á

uint64 serverConnectionHandlerID;
VirtualServerProperties flag;
char** result;

Parameters

serverConnectionHandlerID
ID of the server connection handler on which the virtual server property is queried.
clientID
ID of the client whose property is queried.
flag
Virtual server propery to query, see below.
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.
The returned type uint64 is defined as __int64 on Windows and uint64_t on Linux and Mac OS X. See the header public_definitions.h. This function is currently only used for the flag VIRTUALSERVER_UPTIME.

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

enum VirtualServerProperties {
  VIRTUALSERVER_UNIQUE_IDENTIFIER = 0, //available when connected, can be used to identify this particular
                                       //server installation
  VIRTUALSERVER_NAME,                  //available and always up-to-date when connected
  VIRTUALSERVER_WELCOMEMESSAGE,        //available when connected, not updated while connected
  VIRTUALSERVER_PLATFORM,              //available when connected
  VIRTUALSERVER_VERSION,               //available when connected
  VIRTUALSERVER_MAXCLIENTS,            //only available on request (=> requestServerVariables), stores the
                                       //maximum number of clients that may currently join the server
  VIRTUALSERVER_PASSWORD,              //not available to clients, the server password
  VIRTUALSERVER_CLIENTS_ONLINE,        //only available on request (=> requestServerVariables),
  VIRTUALSERVER_CHANNELS_ONLINE,       //only available on request (=> requestServerVariables),
  VIRTUALSERVER_CREATED,               //available when connected, stores the time when the server was created
  VIRTUALSERVER_UPTIME,                //only available on request (=> requestServerVariables), the time
                                       //since the server was started
  VIRTUALSERVER_CODEC_ENCRYPTION_MODE, //available and always up-to-date when connected
  VIRTUALSERVER_ENDMARKER,
};

VIRTUALSERVER_UNIQUE_IDENTIFIER
Unique ID for this virtual server. Stays the same after restarting the server application. Always available when connected.
VIRTUALSERVER_NAME
Name of this virtual server. Always available when connected.
VIRTUALSERVER_WELCOMEMESSAGE
Optional welcome message sent to the client on login. This value should be queried by the client after connection has been established, it is not updated afterwards.
VIRTUALSERVER_PLATFORM
Operating system used by this server. Always available when connected.
VIRTUALSERVER_VERSION
Application version of this server. Always available when connected.
VIRTUALSERVER_MAXCLIENTS
Defines maximum number of clients which may connect to this server. Needs to be requested using ts3client_requestServerVariables.
VIRTUALSERVER_PASSWORD
Optional password of this server. Not available to clients.
VIRTUALSERVER_CLIENTS_ONLINE
VIRTUALSERVER_CHANNELS_ONLINE
Number of clients and channels currently on this virtual server. Needs to be requested using ts3client_requestServerVariables.
VIRTUALSERVER_CREATED
Time when this virtual server was created. Always available when connected.
VIRTUALSERVER_UPTIME
Uptime of this virtual server. Needs to be requested using ts3client_requestServerVariables.
VIRTUALSERVER_CODEC_ENCRYPTION_MODE
Defines if voice data encryption is configured per channel, globally forced on or globally forced off for this virtual server. The default behaviour is configure per channel, in this case modifying the channel property CHANNEL_CODEC_IS_UNENCRYPTED defines voice data encryption of individual channels.
Virtual server encryption mode can be set to the following parameters:
```
enum CodecEncryptionMode {
   CODEC_ENCRYPTION_PER_CHANNEL = 0,
   CODEC_ENCRYPTION_FORCED_OFF,
   CODEC_ENCRYPTION_FORCED_ON,
};
```
This property is always available when connected.

Example code checking the number of clients online, obviously an integer value:

int clientsOnline;

if(ts3client_getServerVariableAsInt(scHandlerID, VIRTUALSERVER_CLIENTS_ONLINE, &clientsOnline) == ERROR_ok)
    printf("There are %d clients online\n", clientsOnline);

A client can request refreshing the server information with:

unsigned int ts3client_requestServerVariables( serverConnectionHandlerID); á

uint64 serverConnectionHandlerID;

The following event informs the client when the requested information is available:

unsigned int onServerUpdatedEvent( serverConnectionHandlerID); á

uint64 serverConnectionHandlerID;

The following event notifies the client when virtual server information has been edited:

`void onServerEditedEvent(`	`serverConnectionHandlerID`,	á
á	`editerID`,	á
á	`editerName`,	á
á	`editerUniqueIdentifier)`;	á

uint64 serverConnectionHandlerID;
anyID editerID;
const char* editerName;
const char* editerUniqueIdentifier;

Parameters

serverConnectionHandlerID
ID of the server connection handler which virtual server information has been changed.
editerID
ID of the client who edited the information. If zero, the server is the editor.
editerName
Name of the client who edited the information.
editerUniqueIdentifier
Unique ID of the client who edited the information.

á		á
Channel sortingá		áInteracting with the server