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 |
---|---|
Result variables should only be accessed if the function returned |
![]() | Important |
---|---|
Some Client Lib functions dynamically allocate memory which has to be freed by the caller using |
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
errorCode
The error code returned from all Client 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 ts3client_freeMemory
.
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
serverConnectionHandlerID
The connection handler ID of the server who sent the error event.
errorMessage
String containing a verbose error message, encoded in UTF-8 format.
error
Error code as defined in public_errors.h
.
returnCode
String containing the return code if it has been set by the Client Lib function call which caused this error event.
extraMessage
Can contain additional information about the occured error. If no additional information is available, this parameter is an empty string.