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(uint64 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