Server information

Information related to a virtual server can be queried and modified.

Available server properties are described in VirtualServerProperties and VirtualServerPropertiesSDK.

Note

The server always has all the information about all servers that exist.

Limitations regarding availability mentioned for the variables are thus of no concern for the server.

Warning

Servers that are stopped using ts3server_stopVirtualServer() no longer exist within the server library and querying them will thus fail.

Query server information

To query server information use one of the following functions, depending on the type of the information you want to query.

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

get the value of a server variable

Parameters:

  • serverID – the server of which to get a variable value

  • flag – specifies for which variable to get the value. One of the values from the VirtualServerProperties enum

  • result – address of a variable to receive the result

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

unsigned int ts3server_getVirtualServerVariableAsUInt64(uint64 serverID, enum VirtualServerProperties flag, uint64 *result)

get the value of a server variable

Parameters:

  • serverID – the server of which to get a variable value

  • flag – specifies for which variable to get the value. One of the values from the VirtualServerProperties enum

  • result – address of a variable to receive the result.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

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

get the value of a server variable

Parameters:

  • serverID – the server of which to get a variable value

  • flag – specifies for which variable to get the value. One of the values from the VirtualServerProperties enum

  • result – address of a variable to receive a utf8 encoded c string containing the value. Memory is allocated by the server library and must be freed by the caller using ts3server_freeMemory

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Example

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

1int clientsOnline;
2
3if (ts3server_getVirtualServerVariableAsInt(serverID, VIRTUALSERVER_CLIENTS_ONLINE, &clientsOnline) == ERROR_ok) {
4    printf("There are %d clients online\n", clientsOnline);
5}

Change server information

Server information can be modified using

unsigned int ts3server_setVirtualServerVariableAsInt(uint64 serverID, enum VirtualServerProperties flag, int value)

set a new value for a server variable

After you’re done setting all the variables you need to change, a call to ts3server_flushVirtualServerVariable is necessary to publish the changes

Parameters:

  • serverID – specifies which server to set the variable on

  • flag – specifies which server variable to set. One of the values from the VirtualServerProperties enum

  • value – the new value to set

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

unsigned int ts3server_setVirtualServerVariableAsUInt64(uint64 serverID, enum VirtualServerProperties flag, uint64 value)

set a new value for a server variable

After you’re done setting all the variables you need to change, a call to ts3server_flushVirtualServerVariable is necessary to publish the changes

Parameters:

  • serverID – specifies which server to set the variable on

  • flag – specifies which server variable to set. One of the values from the VirtualServerProperties enum

  • value – the new value to set

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

unsigned int ts3server_setVirtualServerVariableAsString(uint64 serverID, enum VirtualServerProperties flag, const char *value)

set a new value for a server variable

After you’re done setting all the variables you need to change, a call to ts3server_flushVirtualServerVariable is necessary to publish the changes

Parameters:

  • serverID – specifies which server to set the variable on

  • flag – specifies which server variable to set. One of the values from the VirtualServerProperties enum

  • value – the new value to set

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Important

After modifying one or more server variables, you must flush the changes using ts3server_flushVirtualServerVariable().

Example

Example: Change the servers welcome message:

1if (ts3server_setVirtualServerVariableAsString(serverID, VIRTUALSERVER_WELCOMEMESSAGE, "New welcome message") != ERROR_ok) {
2    printf("Error setting server welcomemessage\n");
3    return;
4}
5
6if (ts3server_flushVirtualServerVariable(serverID) != ERROR_ok) {
7    printf("Error flushing server variable\n");
8}