Error handling

Each Server 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;

/* welcomeMsg memory is allocated if error is ERROR_ok */
error = ts3server_getVirtualServerVariableAsString(serverID, VIRTUALSERVER_WELCOMEMESSAGE, &welcomeMsg);
if(error != ERROR_ok) {
    /* Handle error */
    return;
}
/* Use welcomeMsg... */
ts3server_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 Server Lib functions dynamically allocate memory which has to be freed by the caller using ts3server_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 will likely result in a segmentation fault.

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


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

unsigned int ts3server_getGlobalErrorMessage(errorCode,  
 error); 
unsigned int errorCode;
char** error;
 

Parameters

Example:

unsigned int error;
char* version;

error = ts3server_getServerLibVersion(&version);  /* Calling some Server Lib function */
if(error != ERROR_ok) {
    char* errorMsg;
    if(ts3server_getGlobalErrorMessage(error, &errorMsg) == ERROR_ok) {  /* Query printable error */
        printf("Error querying client ID: %s\n", errorMsg);
	ts3server_freeMemory(errorMsg);  /* Release memory only if function succeeded */
    }
}