Calling Client Lib functions

## Calling Client Lib functions

Client Lib functions follow a common pattern. They always return an error code or `ERROR_ok` on success. If there is a result variable, it is always the last variable in the functions parameters list.

    ERROR ts3client_FUNCNAME(arg1, arg2, ..., &result);

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

In those cases where the result variable is a basic type (int, float etc.), the memory for the result variable has to be declared by the caller. Simply pass the address of the variable to the Client Lib function.

    int result;

    if(ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
        /* Use result variable */
    } else {
        /* Handle error, result variable is undefined */
    }

If the result variable is a pointer type (C strings, arrays etc.), the memory is allocated by the Client Lib function. In that case, the caller has to release the allocated memory later by 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.

    char* result;

    if(ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
        /* Use result variable */
        ts3client_freeMemory(result);  /* Release result variable */
    } else {
        /* Handle error, result variable is undefined. Do not access or release it. */
    }

| Note
Client Lib functions are thread-safe. It is possible to access the Client Lib from several threads at the same time.

### Return code

Client Lib functions that interact with the server take an additional parameter `returnCode`, which can be used to find out which action results in a later server error. If you pass a custom string as return code, the `onServerErrorEvent` callback will receive the same custom string in its `returnCode` parameter. If no error occured, `onServerErrorEvent` will indicate success py passing the error code `ERROR_ok`.

Pass NULL as `returnCode` if you do not need the feature. In this case, if no error occurs `onServerErrorEvent` will not be called.

An example, request moving a client:

    ts3client_requestClientMove(scHandlerID, clientID, newChannelID, password, "MyClientMoveReturnCode");

If an error occurs, the `onServerErrorEvent` callback is called:

    void my_onServerErrorEvent(anyID serverConnectionHandlerID, const char* errorMessage,
                               unsigned int error, const char* returnCode, const char* extraMessage) {
        if(strcmp(returnCode, "MyClientMoveReturnCode")) == 0) {
            /* We know this error is the reaction to above called function as we got the same returnCode */
    	if(error == ERROR_ok) {
    	    /* Success */
    	}
    }

Overview of header files |  | Initializing