Logging

## Logging

The TeamSpeak 3 Client Lib offers basic logging functions:

`unsigned int ts3client_logMessage(` | logMessage, |
| severity, |
| channel, |
| logID`)`; |

`const char* logMessage`;
`LogLevel severity`;
`const char* channel`;
`anyID logID`;

Parameters

- `logMessage`

  Text written to log.

- `severity`

  The level of the message, warning or error. Defined by the enum LogLevel in `clientlib_publicdefinitions.h`:

      enum LogLevel {
          LogLevel_CRITICAL = 0, //these messages stop the program
          LogLevel_ERROR,        //everything that is really bad, but not so bad we need to shut down
          LogLevel_WARNING,      //everything that *might* be bad
          LogLevel_DEBUG,        //output that might help find a problem
          LogLevel_INFO,         //informational output, like "starting database version x.y.z"
          LogLevel_DEVEL         //developer only output (will not be displayed in release mode)
      };

- `channel`

  Custom text to categorize the message channel (i.e. "Client", "Sound").

  Pass an empty string if unused.

- `logID`

  Server connection handler ID to identify the current server connection when using multiple connections.

  Pass 0 if unused.

All strings need to be encoded in UTF-8 format.

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

Log messages can be printed to stdout, logged to a file `logs/ts3client_[date]__[time].log` and sent to user-defined callbacks. The log output behaviour is defined when initialzing the client library with `ts3client_initClientLib`.

Unless user-defined logging is used, program execution will halt on a log message with severity `LogLevel_CRITICAL`.

### User-defined logging

If user-defined logging was enabled when initialzing the Client Lib by passing `LogType_USERLOGGING` to the `usedLogTypes` parameter of `ts3client_initClientLib`, log messages will be sent to the following callback, which allows user customizable logging and handling or critical errors:

`void onUserLoggingMessageEvent(` | logMessage, |
| logLevel, |
| logChannel, |
| logID, |
| logTime, |
| completeLogString`)`; |

`const char* logMessage`;
`int logLevel`;
`const char* logChannel`;
`anyID logID`;
`const char* logTime`;
`const char* completeLogString`;

Most callback parameters reflect the arguments passed to the `logMessage` function.

Parameters

- `logMessage`

  Actual log message text.

- `logLevel`

  Severity of log message, defined by the enum LogLevel. Note that only log messages of a level higher than the one configured with `ts3client_setLogVerbosity` will appear.

- `logChannel`

  Optional custom text to categorize the message channel.

- `logID`

  Server connection handler ID identifying the current server connection when using multiple connections.

- `logTime`

  String with date and time when the log message occured.

- `completeLogString`

  Provides a verbose log message including all previous parameters for convinience.

The severity of log messages that are passed to above callback can be configured with:

`unsigned int ts3client_setLogVerbosity(` | logVerbosity`)`; |

`enum LogLevel logVerbosity`;

Parameters

- `logVerbosity`

  Only messages with a log level equal or higher than `logVerbosity` will be sent to the callback. The default value is `LogLevel_DEVEL`.

  For example, after calling

      ts3client_setLogVerbosity(LogLevel_ERROR);

  only log messages of level `LogLevel_ERROR` and `LogLevel_CRITICAL` will be passed to `onUserLoggingMessageEvent`.

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

Error handling |  | Using playback and capture modes and devices