Server information

Query server information

Information related to a virtual server can be queried with::

unsigned int ts3server_getVirtualServerVariableAsInt(serverID,  
 flag,  
 result); 
uint64 serverID;
VirtualServerProperties flag;
int* result;
 

unsigned int ts3server_getVirtualServerVariableAsString(serverID,  
 flag,  
 result); 
uint64 serverID;
VirtualServerProperties flag;
char** result;
 

Parameters

  • serverID

    ID of the virtual server of which the property is queried.

  • flag

    Virtual server 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 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 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.

  • VIRTUALSERVER_NAME

    Name of this virtual server.

  • VIRTUALSERVER_WELCOMEMESSAGE

    Optional welcome message sent to the client on login.

  • VIRTUALSERVER_PLATFORM

    Operating system used by this server.

  • VIRTUALSERVER_VERSION

    Application version of this server.

  • VIRTUALSERVER_MAXCLIENTS

    Defines maximum number of clients which may connect to this server.

  • VIRTUALSERVER_PASSWORD

    Optional password of this server.

    If a password is set or removed by modifying this field, VIRTUALSERVER_FLAG_PASSWORD will be automatically adjusted.

  • VIRTUALSERVER_CLIENTS_ONLINE

    VIRTUALSERVER_CHANNELS_ONLINE

    Number of clients and channels currently on this virtual server.

  • VIRTUALSERVER_CREATED

    Time when this virtual server was created.

  • VIRTUALSERVER_UPTIME

    Uptime of this virtual server.

  • 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 checking the number of clients online, obviously an integer value:

int clientsOnline;

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

Setting server information

Change server variables with the following functions:

unsigned int ts3server_setVirtualServerVariableAsInt(serverID,  
 flag,  
 value); 
uint64 serverID;
ChannelProperties flag;
int value;
 

unsigned int ts3server_setVirtualServerVariableAsString(serverID,  
 flag,  
 value); 
uint64 serverID;
ChannelProperties flag;
const char* value;
 

Parameters

  • serverID

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

  • flag

    Virtual server propery to change, see above.

  • value

    Value the virtual server 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 server variables, you must flush the changes.

unsigned int ts3server_flushVirtualServerVariable(serverID); 
uint64 serverID;
 

Example: Change the servers welcome message:

if(ts3server_setVirtualServerVariableAsString(serverID, VIRTUALSERVER_WELCOMEMESSAGE,
                                              "New welcome message") != ERROR_ok) {
    printf("Error setting server welcomemessage\n");
    return;
}

if(ts3server_flushVirtualServerVariable(serverID) != ERROR_ok) {
    printf("Error flushing server variable\n");
}