Getting started

The callback mechanism

The communication from Client Lib to Client UI takes place using callbacks. The SDK user has to define a series of function pointers using the ClientUIFunctions structure. These callbacks are used to forward any incoming server actions to the SDK user for further processing.

Note

All client lib callbacks are asynchronous, except for the sound callbacks which allow to directly manipulate the sound buffer.

A callback example in C:

static void my_onConnectStatusChangeEvent_Callback(uint64 serverConnectionHandlerID, int newStatus, int errorNumber) {
    printf("Changed connection status to %d on connection %llu with error 0x%04X\n", newStatus, serverConnectionHandlerID, errorNumber);
}

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

Before calling ts3client_initClientLib(), create an instance of ClientUIFunctions , initialize all function pointers with NULL and assign the structs function pointers to your callback functions:

unsigned int error;

/* Create struct */
ClientUIFunctions clUIFuncs;

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

/* Assign those function pointers you implemented */
clUIFuncs.onConnectStatusChangeEvent = my_onConnectStatusChangeEvent_Callback;
clUIFuncs.onNewChannelEvent          = my_onNewChannelEvent_Callback;
(...)

/* Initialize client lib with callback function pointers */
error = ts3client_initClientLib(&clUIFuncs, NULL, LogType_FILE | LogType_CONSOLE);
if (error != ERROR_ok) {
    printf("Error initializing clientlib: %d\n", error);
    (...)
}

Important

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

The individual callbacks are described in ClientUIFunctions.

Initializing

When starting the client, initialize the Client Lib with

unsigned int ts3client_initClientLib(const struct ClientUIFunctions *functionPointers, const struct ClientUIFunctionsRare *functionRarePointers, int usedLogTypes, const char *logFileFolder, const char *resourcesFolder)

initializes the client library and defines callback functions

This is the first function you need to call, before this all calls to the client library will fail. In this call you will also set the functions you would like to have called when certain changes happen on the client side as well as on connected servers.

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 struct

• functionRarePointers – similar to the functionPointers parameter. These are not available in the SDK, so SDK users should pass a nullptr here.

• 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

• resourcesFolder – path to the directory in which the soundbackends folder is located. Required to be able to load the sound backends and process audio.

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.

Querying the library version

The complete Client Lib version string can be queried with

unsigned int ts3client_getClientLibVersion(char **result)

Get the version string of the client library.

Parameters:

• result – Pointer to a char* variable that the client library will allocate memory for. If the return value is ERROR_ok the memory was allocated and the variable pointed to will contain the client library version. You need to free the variable pointed to by using ts3client_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 ts3client_getClientLibVersionNumber(uint64 *result)

Get the version number of the client library.

Parameters:

• result – Pointer to a variable to store the client library version number into

Returns:

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

Examples

Query the client lib version:

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

To only get the version number:

unsigned int error;
uint64 version;
error = ts3client_getClientLibVersionNumber(&version);
if (error != ERROR_ok) {
    printf("Error querying clientlib version number: %d\n", error);
    return;
}
printf("Client library version number: %ld\n", version);  /* Print version */

Shutting down

Before exiting the client application, you should disconnect from any servers you’re connected to (ts3client_stopConnection()) and destroy the connection handler (ts3client_destroyServerConnectionHandler()). After that the Client Lib should be shut down using

unsigned int ts3client_destroyClientLib()

destroys the client library. Must not be called from within a callback.

This is the last function to call, after calling this function you will no longer be able to use client library functions.

Returns:

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

Any call to client lib functions after shutting down has undefined results.

Caution

Never destroy the client lib from within a callback. This might result in segmentation fault.

Error handling

Each Client Lib function returns either ERROR_ok on success or an error value as defined in Ts3ErrorType 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.

Important

Client Lib functions returning C-strings or arrays dynamically allocate memory which has to be freed by the caller using ts3client_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 could crash the application.

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

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

unsigned int ts3client_getErrorMessage(unsigned int errorCode, char **error)

Retrieve human readable description for an error code.

Parameters:

• errorCode – the error code from the Ts3ErrorType enum to retrieve the description for

• error – address of a variable to receive a c string with the error description. Memory is allocated by the client lib and must be freed by caller using ts3client_freeMemory

Returns:

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

Error callback

In addition to actively querying errors like above, error codes can be sent by the server to the client through the following callback

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onServerErrorEvent)(uint64 serverConnectionHandlerID, const char *errorMessage, unsigned int error, const char *returnCode, const char *extraMessage)

called after an action was performed by us. Tells whether the action was successful or which error occurred.

Param serverConnectionHandlerID:

specifies on which connection the callback was called

Param errorMessage:

utf8 encoded c string describing the error

Param error:

the error code the action finished with. One of the values from the Ts3ErrorType enum.

Param returnCode:

a c string identifying the action that caused this error. This is the same string given as returnCode to function calls that request an action on the server

Param extraMessage:

utf8 encoded c string containing additional information if available.

Examples

unsigned int error;
char* welcomeMsg;

error = ts3client_getServerVariableAsString(serverConnectionHandlerID, VIRTUALSERVER_WELCOMEMESSAGE, &welcomeMsg);
if (error == ERROR_ok) {
    /* Use welcomeMsg... */
    ts3client_freeMemory(welcomeMsg);  /* Release memory *only* if function did not return an error */
} else {
    /* Handle error */
    /* Do not access or release welcomeMessage, the variable is undefined */
}

unsigned int error;
anyID myID;

error = ts3client_getClientID(scHandlerID, &myID);  /* Calling some Client Lib function */
if (error != ERROR_ok) {
    char* errorMsg;
    if (ts3client_getErrorMessage(error, &errorMsg) == ERROR_ok) {  /* Query printable error */
        printf("Error querying client ID: %s\n", errorMsg);
        ts3client_freeMemory(errorMsg);  /* Release memory */
    }
}