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`

  If file logging is used, this defines the location where the logs are written 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