Initializing

## Initializing

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

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

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

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
  If `LogType_NO_NETLOGGING` is not passed, the Client Lib will send notifications of each warning, error and critical error to a TeamSpeak-Systems webserver. This data is used for analysis and debugging during the TeamSpeak 3 development. We recommend to leave netlogging enabled in debug builds. 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.

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(anyID 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 struct to avoid polluting the SDK headers with code used only internally.

Calling Client Lib functions |  | Querying the library version