Server Lib functions follow a common pattern. They always return an error code or ERROR_ok
on success. If there is a result variable, it is always the last variable in the functions parameters list.
ERROR ts3server_FUNCNAME(arg1, arg2, ..., &result);
Result variables should only be accessed if the function returned ERROR_ok
. Otherwise the state of the result variable is undefined.
In those cases where the result variable is a basic type (int, float etc.), the memory for the result variable has to be declared by the caller. Simply pass the address of the variable to the Server Lib function.
int result; if(ts3server_XXX(arg1, arg2, ..., &result) == ERROR_ok) { /* Use result variable */ } else { /* Handle error, result variable is undefined */ }
If the result variable is a pointer type (C strings, arrays etc.), the memory is allocated by the Server Lib function. In that case, the caller has to release the allocated memory later by 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.
char* result; if(ts3server_XXX(arg1, arg2, ..., &result) == ERROR_ok) { /* Use result variable */ ts3server_freeMemory(result); /* Release result variable */ } else { /* Handle error, result variable is undefined. Do not access or release it. */ }
![]() | Note |
---|---|
Server Lib functions are thread-safe. It is possible to access the Server Lib from several threads at the same time. |