Initializing

Initializing
á	á	á

When starting the client, initialize the Client Lib with a call to

`unsigned int ts3client_initClientLib(`	`functionPointers`,	á
á	`functionRarePointers`,	á
á	`usedLogTypes`,	á
á	`logFileFolder`,	á
á	`resourcesFolder)`;	á

const struct ClientUIFunctions* functionPointers;
const struct ClientUIFunctionsRare* functionRarePointers;
int usedLogTypes;
const char* logFileFolder;
const char* resourcesFolder;

Parameters

functionPointers
Callback function pointers. See below.
functionRarePointers
Unused by SDK, pass NULL.

usedLogTypes

Defines the log output types. The Client Lib can output log messages (called by ts3client_logMessage) to a file (located in the logs directory relative to the client executable), to stdout or to user defined callbacks. If user callbacks are activated, the onUserLoggingMessageEvent event needs to be implemented.

Available values are defined by the enum LogTypes (see public_definitions.h):

enum LogTypes {
    LogType_NONE          = 0x0000,
    LogType_FILE          = 0x0001,
    LogType_CONSOLE       = 0x0002,
    LogType_USERLOGGING   = 0x0004,
    LogType_NO_NETLOGGING = 0x0008,
    LogType_DATABASE      = 0x0010,
};

Multiple log types can be combined with a binary OR. If only LogType_NONE is used, local logging is disabled.

	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

LogType_NO_NETLOGGING is no longer used. Previously this controlled if the Client Lib would send warning, error and critical log entries to a webserver for analysis. As netlogging does not occur anymore, this flag has no effect anymore.

LogType_DATABASE has no effect in the Client Lib, this is only used by the server.

logFileFolder
Location where the logfiles produced if file logging is enabled will be saved to. Pass NULL for the default behaviour, which is to use a folder called logs in the current working directory.
resourcesFolder
Resource path pointing to the directory where the soundbackends folder is located. Required so your application finds the sound backend shared libraries. This should usually point to the root or bin directory of your application, depending where the soundbackends directory is located.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

	Note
	This function must not be called more than once.

The callback mechanism

The communication from Client Lib to Client UI takes place using callbacks. The Client UI has to define a series of function pointers using the struct ClientUIFunctions (see clientlib.h). These callbacks are used to forward any incoming server actions to the Client UI for further processing.

A callback example in C:

static void my_onConnectStatusChangeEvent_Callback(uint64 serverConnectionHandlerID,
                                                   int newStatus,
                                                   int errorNumber) {
    /* Implementation */
}

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

Before calling ts3client_initClientLib, create an instance of struct 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 crash when trying to calling them.

	Note
	All callbacks used in the SDK are found in the struct ClientUIFunctions (see `public_definitions.h`). Callbacks bundled in the struct ClientUIFunctionsRare are not used by the SDK. These callbacks were split in a separate structs to avoid polluting the SDK headers with code used only internally.

á	á	á
Calling Client Lib functionsá		áQuerying the library version