28 lines
7.8 KiB
HTML
28 lines
7.8 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Error handling</title><link rel="stylesheet" href="ts3doc.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="up" href="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="prev" href="ar01s10.html" title="Disconnecting from a server"><link rel="next" href="ar01s12.html" title="Logging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><img id="logo" src="images/logo.png"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Error handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s10.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s12.html"><img src="images/next.png" alt="Next"></a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="errorhandling"></a>Error handling</h2></div></div></div><p>Each Client Lib function returns either <em class="structfield"><code>ERROR_ok</code></em> on success or an error value as defined in <code class="filename">public_errors.h</code> if the function fails.</p><p>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 <em class="structfield"><code>ERROR_client_invalid_id</code></em>.</p><p>Example:</p><pre class="programlisting">unsigned int error;
|
||
char* welcomeMsg;
|
||
|
||
error = ts3client_getServerVariableAsString(serverConnectionHandlerID,
|
||
VIRTUALSERVER_WELCOMEMESSAGE,
|
||
&welcomeMsg);
|
||
if(error == ERROR_ok) {
|
||
/* Use welcomeMsg... */
|
||
ts3client_freeMemory(welcomeMsg); /* Release memory *only* if function did not return an error */
|
||
} else {
|
||
/* Handle error */
|
||
/* Do not access or release welcomeMessage, the variable is undefined */
|
||
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Client Lib functions returning C-strings or arrays dynamically allocate memory which has to be freed by the caller using <a class="link" href="ar01s28.html#freememory"><code class="function">ts3client_freeMemory</code></a>. It is important to <span class="emphasis"><em>only</em></span> access and release the memory if the function returned <em class="structfield"><code>ERROR_ok</code></em>. Should the function return an error, the result variable is uninitialized, so freeing or accessing it could crash the application.</p></td></tr></table></div><p>See the section <a class="link" href="ar01s04.html" title="Calling Client Lib functions">Calling Client Lib functions</a> for additional notes and examples.</p><div class="literallayout"><p><br>
|
||
</p></div><p>A printable error string for a specific error code can be queried with
|
||
</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">unsigned int <b class="fsfunc">ts3client_getErrorMessage</b>(</code></td><td><var class="pdparam">errorCode</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">error</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>unsigned int <var class="pdparam">errorCode</var></code>;<br><code>char** <var class="pdparam">error</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434878992"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>errorCode</code></em></p><p>The error code returned from all Client Lib functions.</p></li><li><p><em class="parameter"><code>error</code></em></p><p>Address of a variable that receives the error message string, encoded in UTF-8 format. Unless the return value of the function is not <em class="structfield"><code>ERROR_ok</code></em>, the string should be released with <a class="link" href="ar01s28.html#freememory"><code class="function">ts3client_freeMemory</code></a>.</p></li></ul></div><p>Example:</p><pre class="programlisting">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 */
|
||
}
|
||
}</pre><div class="literallayout"><p><br>
|
||
</p></div><p>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:</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">onServerErrorEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">errorMessage</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">error</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">returnCode</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">extraMessage</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>const char* <var class="pdparam">errorMessage</var></code>;<br><code>unsigned int <var class="pdparam">error</var></code>;<br><code>const char* <var class="pdparam">returnCode</var></code>;<br><code>const char* <var class="pdparam">extraMessage</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434866416"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>The connection handler ID of the server who sent the error event.</p></li><li><p><em class="parameter"><code>errorMessage</code></em></p><p>String containing a verbose error message, encoded in UTF-8 format.</p></li><li><p><em class="parameter"><code>error</code></em></p><p>Error code as defined in <code class="filename">public_errors.h</code>.</p></li><li><p><em class="parameter"><code>returnCode</code></em></p><p>String containing the return code if it has been set by the Client Lib function call which caused this error event.</p><p>See <a class="link" href="ar01s04.html#callingReturnCode" title="Return code">return code documentation</a>.</p></li><li><p><em class="parameter"><code>extraMessage</code></em></p><p>Can contain additional information about the occured error. If no additional information is available, this parameter is an empty string.</p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s10.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s12.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Disconnecting from a server </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> Logging</td></tr></table></div></body></html>
|