22 lines
5.9 KiB
HTML
22 lines
5.9 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Calling Client Lib functions</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="ar01s03.html" title="Overview of header files"><link rel="next" href="ar01s05.html" title="Initializing"></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">Calling Client Lib functions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.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="ar01s05.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="calling"></a>Calling Client Lib functions</h2></div></div></div><p>Client Lib functions follow a common pattern. They always return an error code or <em class="structfield"><code>ERROR_ok</code></em> on success. If there is a result variable, it is always the last variable in the functions parameters list.</p><pre class="programlisting">ERROR ts3client_FUNCNAME(arg1, arg2, ..., &result);</pre><p>Result variables should <span class="emphasis"><em>only</em></span> be accessed if the function returned <em class="structfield"><code>ERROR_ok</code></em>. Otherwise the state of the result variable is undefined.</p><p>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 Client Lib function.</p><pre class="programlisting">int result;
|
||
|
||
if(ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
|
||
/* Use result variable */
|
||
} else {
|
||
/* Handle error, result variable is undefined */
|
||
}</pre><p>If the result variable is a pointer type (C strings, arrays etc.), the memory is allocated by the Client Lib function. In that case, the caller has to release the allocated memory later by using <code class="function">ts3client_freeMemory</code>. 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><pre class="programlisting">char* result;
|
||
|
||
if(ts3client_XXX(arg1, arg2, ..., &result) == ERROR_ok) {
|
||
/* Use result variable */
|
||
ts3client_freeMemory(result); /* Release result variable */
|
||
} else {
|
||
/* Handle error, result variable is undefined. Do not access or release it. */
|
||
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Client Lib functions are <span class="emphasis"><em>thread-safe</em></span>. It is possible to access the Client Lib from several threads at the same time.</p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="callingReturnCode"></a>Return code</h3></div></div></div><a class="indexterm" name="idm44835435141872"></a><a class="indexterm" name="idm44835435141360"></a><p>Client Lib functions that interact with the server take an additional parameter <em class="parameter"><code>returnCode</code></em>, which can be used to find out which action results in a later server error. If you pass a custom string as return code, the <code class="function">onServerErrorEvent</code> callback will receive the same custom string in its <em class="parameter"><code>returnCode</code></em> parameter. If no error occured, <code class="function">onServerErrorEvent</code> will indicate success py passing the error code <em class="structfield"><code>ERROR_ok</code></em>.</p><p>Pass NULL as <em class="parameter"><code>returnCode</code></em> if you do not need the feature. In this case, if no error occurs <code class="function">onServerErrorEvent</code> will <span class="emphasis"><em>not</em></span> be called.</p><p>An example, request moving a client:</p><pre class="programlisting">ts3client_requestClientMove(scHandlerID, clientID, newChannelID, password, "MyClientMoveReturnCode");</pre><p>If an error occurs, the <code class="function">onServerErrorEvent</code> callback is called:</p><pre class="programlisting">void my_onServerErrorEvent(uint64 serverConnectionHandlerID, const char* errorMessage,
|
||
unsigned int error, const char* returnCode, const char* extraMessage) {
|
||
if(strcmp(returnCode, "MyClientMoveReturnCode")) == 0) {
|
||
/* We know this error is the reaction to above called function as we got the same returnCode */
|
||
if(error == ERROR_ok) {
|
||
/* Success */
|
||
}
|
||
}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03.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="ar01s05.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Overview of header files </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"> Initializing</td></tr></table></div></body></html>
|