Error handling

## Error handling

Each Client Lib function returns either `ERROR_ok` on success or an error value as defined in `public_errors.h` if the function fails.

The returned error codes are organized in groups, where the first byte defines the error group and the second the count within the group: The naming convention is ERROR_<group>_<error>, for example `ERROR_client_invalid_id`.

Example:

    unsigned int error;
    char* welcomeMsg;

    error = ts3client_getServerVariableAsString(serverConnectionHandlerID,
                                                VIRTUALSERVER_WELCOMEMESSAGE,
                                                &welcomeMsg);
    if(error != ERROR_ok) {
        /* Handle error */
        return;
    }
    /* Use welcomeMsg... */
    ts3client_freeMemory(welcomeMsg);  /* Release memory *only* if function did not return an error */

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

| Important
Some Client Lib functions dynamically allocate memory which has to be freed by the caller 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.

See the section Calling Client Lib functions for additional notes and examples.

A printable error string for a specific error code can be queried with

`unsigned int ts3client_getErrorMessage(` | errorCode, |
| error`)`; |

`unsigned int errorCode`;
`char** error`;

Parameters

- `errorCode`

  The error code returned from all Client Lib functions.

- `error`

  Address of a variable that receives the error message string, encoded in UTF-8 format. Unless the return value of the function is not `ERROR_ok`, the string should be released with `ts3client_freeMemory`.

Example:

    unsigned int error;
    anyID myID;

    error = ts3client_getClientID(scHandlerID, &myID);  /* Calling some Client Lib function */
    if(error != ERROR_ok) {
        char* errorMsg;
        if(ts3client_getErrorMessage(error, &errorMsg) == ERROR_ok) {  /* Query printable error */
            printf("Error querying client ID: %s\n", errorMsg);
    	ts3client_freeMemory(errorMsg);  /* Release memory only if function succeeded */
        }
    }

In addition to actively querying errors like above, error codes can be sent by the server to the client. In that case the following event is called:

`void onServerErrorEvent(` | serverConnectionHandlerID, |
| errorMessage, |
| error, |
| returnCode, |
| extraMessage`)`; |

`anyID serverConnectionHandlerID`;
`const char* errorMessage`;
`unsigned int error`;
`const char* returnCode`;
`const char* extraMessage`;

Parameters

- `serverConnectionHandlerID`

  The connection handler ID of the server who sent the error event.

- `errorMessage`

  String containing a verbose error message, encoded in UTF-8 format.

- `error`

  Error code as defined in `public_errors.h`.

- `returnCode`

  String containing the return code if it has been set by the Client Lib function call which caused this error event.

  See return code documentation.

- `extraMessage`

  Can contain additional information about the occured error. If no additional information is available, this parameter is an empty string.

Disconnecting from a server |  | Logging