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]Note

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

[Important]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

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