Introduction

This document describes client-side programming with the TeamSpeak 3 SDK. This library, the so-called client lib, encapsulates client-side functionality while keeping the user interface separated and modular.

System requirements

For developing third-party clients with the TeamSpeak 3 Client Lib the following system requirements apply:

• Windows 7, 8.1, 10

• Mac OS X 10.6 and above

• Any recent Linux distribution with libstdc++ 6

Important

The calling convention used in the functions exported by the shared TeamSpeak 3 SDK libaries is cdecl. You must not use another calling convention, like stdcall on Windows, when declaring function pointers to the TeamSpeak 3 SDK libraries. Otherwise stack corruption at runtime may occur.

Overview of header files

The following header files are deployed to SDK developers

• clientlib.h

  Declares the function prototypes and callbacks for the communication between Client Lib and Client UI. While the Client UI makes function calls into the Client Lib using the declared prototypes, the Client Lib calls the Client UI via callbacks.

• clientlib_publicdefinitions.h

  Defines various enums and structs used by the Client UI and Client Lib. These definitions are used by the functions and callbacks declared in clientlib.h

• public_definitions.h

  Defines various enums and structs used by both client- and server-side.

• public_errors.h

  Defines the error codeserror codes returned by every Client Lib function and onServerErrorEvent. Error codes are organized in several groups. The first byte of the error code defines the error group, the second the count within the group.

Calling Client Lib functions

Client Lib functions follow a common pattern. They always return an error code from the Ts3ErrorType or ERROR_ok on success. If there is a result variable, it is always the last variable in the functions parameters list.

ERROR ts3client_FUNCNAME(arg1, arg2, ..., &result);

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

In those cases where the result variable is a basic type (int, float etc.), the memory for the result variable has to be declared by the caller. Simply pass the address of the variable to the Client Lib function ts3client_freeMemory().

int result;

if(ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
    /* Use result variable */
} else {
    /* Handle error, result variable is undefined */
}

If the result variable is a pointer type (C strings, arrays etc.), the memory is allocated by the Client Lib function. In that case, the caller has to release the allocated memory later by 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.

char* result;

if (ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
    /* Use result variable */
    ts3client_freeMemory(result);  /* Release result variable */
} else {
    /* Handle error, result variable is undefined. Do not access or release it. */
}

Note

Client Lib functions are thread-safe. It is possible to access the Client Lib from several threads at the same time.

Return code

Client Lib functions that interact with the server take an additional parameter returnCode, which can be used to find out which action results in a later server error. If you pass a custom string as return code, the onServerErrorEvent() callback will receive the same custom string in its returnCode parameter. If no error occured, onServerErrorEvent() will indicate success by passing the error code ERROR_ok if a return code was specified.

Pass NULL as returnCode if you do not need the feature. In this case, if no error occurs onServerErrorEvent() will not be called.

Example

An example, request moving a client:

ts3client_requestClientMove(scHandlerID, clientID, newChannelID, password, "MyClientMoveReturnCode");

If an error occurs, the onServerErrorEvent() callback is called:

void my_onServerErrorEvent(uint64 serverConnectionHandlerID, const char* errorMessage,
                           unsigned int error, const char* returnCode, const char* extraMessage) {
    if (strcmp(returnCode, "MyClientMoveReturnCode")) == 0) {
        /* We know this error is the reaction to above called function as we got the same returnCode */
    if (error == ERROR_ok) {
        /* Success */
    }
}