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_getServerVariableAsString(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 could crash the application.

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 */
    }
}