Getting started

The callback mechanism

The communication from the Server Lib to the server application takes place using callbacks. The server application has to define a series of function pointers using the ServerLibFunctions struct. These callbacks are used to let the server application hook into the library and receive notifications on certain actions.

A callback example in C:

static void my_onClientConnected_callback(uint64 serverID, anyID clientID, uint64 channelID, unsigned int* removeClientError) {
    printf("Client %u connected on virtual server %u joining channel %u", clientID, serverID, channelID);
}

C++ developers can also use static member functions for the callbacks.

Before calling ts3server_initServerLib(), create an instance of ServerLibFunctions , initialize all function pointers with NULL and point the structs function pointers to your implemented callback functions:

unsigned int error;

/* Create struct */
ServerLibFunctions slFuncs;

/* Initialize all function pointers with NULL */
memset(&slFuncs, 0, sizeof(struct ServerLibFunctions));

/* Assign those function pointers you implemented */
slFuncs.onVoiceDataEvent           = my_onVoiceDataEvent_callback;
slFuncs.onClientStartTalkingEvent  = my_onClientStartTalkingEvent_callback;
slFuncs.onClientStopTalkingEvent   = my_onClientStopTalkingEvent_callback;
slFuncs.onClientConnected          = my_onClientConnected_callback;
slFuncs.onClientDisconnected       = my_onClientDisconnected_callback;
slFuncs.onClientMoved              = my_onClientMoved_callback;
slFuncs.onChannelCreated           = my_onChannelCreated_callback;
slFuncs.onChannelEdited            = my_onChannelEdited_callback;
slFuncs.onChannelDeleted           = my_onChannelDeleted_callback;
slFuncs.onServerTextMessageEvent   = my_onServerTextMessageEvent_callback;
slFuncs.onChannelTextMessageEvent  = my_onChannelTextMessageEvent_callback;
slFuncs.onUserLoggingMessageEvent  = my_onUserLoggingMessageEvent_callback;
slFuncs.onAccountingErrorEvent     = my_onAccountingErrorEvent_callback;
slFuncs.onCustomPacketEncryptEvent = NULL;  // Not used by your application
slFuncs.onCustomPacketDecryptEvent = NULL;  // Not used by your application

/* Initialize library with callback function pointers */
error = ts3server_initServerLib(&slFuncs, LogType_FILE | LogType_CONSOLE);
if (error != ERROR_ok) {
    printf("Error initializing serverlib: %d\n", error);
    (...)
}

Important

As long as you initialize unimplemented callbacks with NULL, the Server Lib won’t attempt to call those function pointers. However, if you leave unimplemented callbacks undefined, the Server Lib will attempt to call them, crashing the application.

The individual callbacks are described in ServerLibFunctions.

Initializing

When starting the server application, initialize the Server Lib with

unsigned int ts3server_initServerLib(const struct ServerLibFunctions *functionPointers, int usedLogTypes, const char *logFileFolder)

initializes the server library and defines callback functions

This is the first function you need to call, before this all calls to the server library will fail. In this call you will also set the functions you would like to have called when certain changes or events happen. This function must not be called multiple times.

Parameters:

• functionPointers – defines which functions in your code are to be called on specific events. Zero initialize it and assign the desired function to call to the respective members of the ServerLibFunctions struct

• usedLogTypes – a combination of values from the LogTypes enum. Specifies which type(s) of logging you would like to use.

• logFileFolder – path in which to create log files. Pass 0 to use the default of using a folder called logs in the working directory.

Returns:

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

Important

This function must not be called more than once.

Note

Logging to console can slow down the application on Windows. Hence we do not recommend to log to the console on Windows other than in debug builds.

Note

During initialization the serverlib will attempt to connect to the TeamSpeak licensing server. This function may block if the licensing server is unreachable.

Querying the library version

The Server Lib version can be queried with

unsigned int ts3server_getServerLibVersion(char **result)

Retrieve the server version string.

Parameters:

• result – address of a variable to receive the server version. Memory is allocated by the server library and must be freed by caller using ts3server_freeMemory

Returns:

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

To get only the version number, which is a part of the complete version string, as numeric value use

unsigned int ts3server_getServerLibVersionNumber(uint64 *result)

Retrieve the server version number.

Parameters:

• result – address of a variable to receive the server version number.

Returns:

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

Example

Query the Server Lib version:

unsigned int error;
char* version;
error = ts3server_getServerLibVersion(&version);
if (error != ERROR_ok) {
    printf("Error querying serverlib version: %d\n", error);
    return;
}
printf("Server library version: %s\n", version);  /* Print version */
ts3server_freeMemory(version);  /* Release string */

Shutting down

Before exiting the application, the Server Lib should be shut down using

unsigned int ts3server_destroyServerLib()

Destroys the server lib. Must not be called from within a callback.

All clients will lose connection and timeout, all servers will terminate. This is the last function to call. After this call you will no longer be able to use any server library functions.

Returns:

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

Any call to Server Lib functions after shutting down has undefined results.

Caution

Never destroy the Server Lib from within a callback function. This might result in a segmentation fault.

Error handling

Each Server Lib function returns either ERROR_ok on success or an error value as defined in the Ts3ErrorType enum if the function fails.

The returned error codes are organized in groups, where the first byte defines the error group and the second the count within the group: The naming convention is ERROR_<group>_<error>, for example ERROR_client_invalid_id.

Note

Result variables should only be accessed if the function returned ERROR_ok. Otherwise the state of the result variable is undefined.

Important

Some Server Lib functions dynamically allocate memory which has to be freed by the caller using ts3server_freeMemory(). It is important to only access and release the memory if the function returned ERROR_ok. Should the function return an error, the result variable is uninitialized, so freeing or accessing it will likely result in a segmentation fault.

See the section Calling Server Lib functions for additional notes and examples.

A printable error string for a specific error code can be queried with

unsigned int ts3server_getGlobalErrorMessage(unsigned int globalErrorCode, char **result)

get a human readable error description string for an error code

Parameters:

• globalErrorCode – the error code to retrieve the description for. One of the values from the Ts3ErrorType enum.

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

Returns:

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

Examples

unsigned int error;
char* welcomeMsg;

/* welcomeMsg memory is allocated if error is ERROR_ok */
error = ts3server_getVirtualServerVariableAsString(serverID, VIRTUALSERVER_WELCOMEMESSAGE, &welcomeMsg);
if (error != ERROR_ok) {
    /* Handle error */
    return;
}
/* Use welcomeMsg... */
ts3server_freeMemory(welcomeMsg);  /* Release memory *only* if function did not return an error */

unsigned int error;
char* version;

error = ts3server_getServerLibVersion(&version);  /* Calling some Server Lib function */
if (error != ERROR_ok) {
    char* errorMsg;
    if (ts3server_getGlobalErrorMessage(error, &errorMsg) == ERROR_ok) {  /* Query printable error */
        printf("Error querying client ID: %s\n", errorMsg);
    ts3server_freeMemory(errorMsg); /* Release memory only if function succeeded */
    }
}