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 |
---|---|
Result variables should only be accessed if the function returned |
![]() | Important |
---|---|
Some Server Lib functions dynamically allocate memory which has to be freed by the caller using |
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
errorCode
The error code returned from all Server Lib functions.
error
Address of a variable that receives the error message string, encoded in UTF-8 format. Unless the return value of the function is not ERROR_ok
, the string should be released with ts3server_freeMemory
.
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 */ } }