sansenhoshi/ts-mobile-go
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 8 Wiki Activity

首次推送

Browse Source
This commit is contained in:
sansen
2026-07-20 19:01:03 +08:00
parent ea01b9cf99
commit ef1bf61f9f
4484 changed files with 937163 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/teamspeak-sdk-3.5.2/doc/client/basic.html
+459
View File
@@ -0,0 +1,459 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting started &mdash; TeamSpeak SDK documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=7f41d439"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Managing server connections" href="connections.html" />
<link rel="prev" title="Introduction" href="intro.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
TeamSpeak SDK
<img src="../_static/logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../errors.html">TeamSpeak Error Codes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../properties.html">Property Enums</a></li>
<li class="toctree-l1"><a class="reference internal" href="../enumerations.html">Structures &amp; Enumerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../client_api.html">TeamSpeak Client Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server_api.html">TeamSpeak Server Functions</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Server</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../server/intro.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/basic.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/list-items.html">List available clients, channels, servers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/vserver-manage.html">Create and stop virtual servers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/advanced-create.html">Advanced virtual server creation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/info.html">Retrieve and store information</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/channels.html">Managing channels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/clients.html">Managing clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/whisper.html">Whisper lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/encryption.html">Custom encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/passwords.html">Custom passwords</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/permissions.html">Permission checks</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/security-salt.html">Security salts and hashes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/disable-commands.html">Disabling protocol commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/filetransfer.html">Filetransfer</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/faq.html">FAQ</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Client</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#the-callback-mechanism">The callback mechanism</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#a-callback-example-in-c">A callback example in C:</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#initializing">Initializing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#querying-the-library-version">Querying the library version</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#shutting-down">Shutting down</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#c.ts3client_destroyClientLib"><code class="docutils literal notranslate"><span class="pre">ts3client_destroyClientLib()</span></code></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#error-handling">Error handling</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#error-callback">Error callback</a></li>
<li class="toctree-l3"><a class="reference internal" href="#id1">Examples</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="connections.html">Managing server connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l1"><a class="reference internal" href="audio.html">Client Audio</a></li>
<li class="toctree-l1"><a class="reference internal" href="wave-files.html">Playing wave files</a></li>
<li class="toctree-l1"><a class="reference internal" href="3dsound.html">3D Sound</a></li>
<li class="toctree-l1"><a class="reference internal" href="whisper.html">Whisper lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="voice-encryption.html">Channel voice data encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="info.html">Retrieve and store information</a></li>
<li class="toctree-l1"><a class="reference internal" href="channels.html">Channel Management</a></li>
<li class="toctree-l1"><a class="reference internal" href="client-list.html">List clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="client-kick.html">Kicking clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="local-mute.html">Muting other clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="textmessages.html">Text chat</a></li>
<li class="toctree-l1"><a class="reference internal" href="filetransfer.html">Filetransfer</a></li>
<li class="toctree-l1"><a class="reference internal" href="encryption.html">Custom encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="passwords.html">Custom passwords</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">TeamSpeak SDK</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Getting started</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="getting-started">
<h1>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h1>
<section id="the-callback-mechanism">
<h2>The callback mechanism<a class="headerlink" href="#the-callback-mechanism" title="Link to this heading"></a></h2>
<p id="c-calling">The communication from Client Lib to Client UI takes place using
callbacks. The SDK user has to define a series of function
pointers using the <a class="reference internal" href="3dsound.html#c.ClientUIFunctions" title="ClientUIFunctions"><code class="xref c c-struct docutils literal notranslate"><span class="pre">ClientUIFunctions</span></code></a> structure.
These callbacks are used to forward any incoming server actions to the
SDK user for further processing.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>All client lib callbacks are asynchronous, except for the sound
callbacks which allow to directly manipulate the sound buffer.</p>
</div>
<section id="a-callback-example-in-c">
<h3>A callback example in C:<a class="headerlink" href="#a-callback-example-in-c" title="Link to this heading"></a></h3>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">my_onConnectStatusChangeEvent_Callback</span><span class="p">(</span><span class="n">uint64</span><span class="w"> </span><span class="n">serverConnectionHandlerID</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">newStatus</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">errorNumber</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Changed connection status to %d on connection %llu with error 0x%04X</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">newStatus</span><span class="p">,</span><span class="w"> </span><span class="n">serverConnectionHandlerID</span><span class="p">,</span><span class="w"> </span><span class="n">errorNumber</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>C++ developers can also use static member functions for the callbacks.</p>
<p>Before calling <a class="reference internal" href="#c.ts3client_initClientLib" title="ts3client_initClientLib"><code class="xref c c-func docutils literal notranslate"><span class="pre">ts3client_initClientLib()</span></code></a>, create an instance of <a class="reference internal" href="3dsound.html#c.ClientUIFunctions" title="ClientUIFunctions"><code class="xref c c-struct docutils literal notranslate"><span class="pre">ClientUIFunctions</span></code></a>
, initialize all function pointers with NULL and assign
the structs function pointers to your callback functions:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="linenos"> 2</span>
<span class="linenos"> 3</span><span class="cm">/* Create struct */</span>
<span class="linenos"> 4</span><span class="n">ClientUIFunctions</span><span class="w"> </span><span class="n">clUIFuncs</span><span class="p">;</span>
<span class="linenos"> 5</span>
<span class="linenos"> 6</span><span class="cm">/* Initialize all function pointers with NULL */</span>
<span class="linenos"> 7</span><span class="n">memset</span><span class="p">(</span><span class="o">&amp;</span><span class="n">clUIFuncs</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">ClientUIFunctions</span><span class="p">));</span>
<span class="linenos"> 8</span>
<span class="linenos"> 9</span><span class="cm">/* Assign those function pointers you implemented */</span>
<span class="linenos">10</span><span class="n">clUIFuncs</span><span class="p">.</span><span class="n">onConnectStatusChangeEvent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">my_onConnectStatusChangeEvent_Callback</span><span class="p">;</span>
<span class="linenos">11</span><span class="n">clUIFuncs</span><span class="p">.</span><span class="n">onNewChannelEvent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">my_onNewChannelEvent_Callback</span><span class="p">;</span>
<span class="linenos">12</span><span class="p">(...)</span>
<span class="linenos">13</span>
<span class="linenos">14</span><span class="cm">/* Initialize client lib with callback function pointers */</span>
<span class="linenos">15</span><span class="n">error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ts3client_initClientLib</span><span class="p">(</span><span class="o">&amp;</span><span class="n">clUIFuncs</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">LogType_FILE</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">LogType_CONSOLE</span><span class="p">);</span>
<span class="linenos">16</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">error</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="linenos">17</span><span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Error initializing clientlib: %d</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">error</span><span class="p">);</span>
<span class="linenos">18</span><span class="w"> </span><span class="p">(...)</span>
<span class="linenos">19</span><span class="p">}</span>
</pre></div>
</div>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>As long as you initialize unimplemented callbacks with NULL, the
Client Lib won’t attempt to call those function pointers. However, if
you leave unimplemented callbacks undefined, the Client Lib will
attempt to call them, crashing the application.</p>
</div>
<p>The individual callbacks are described in <a class="reference internal" href="3dsound.html#c.ClientUIFunctions" title="ClientUIFunctions"><code class="xref c c-struct docutils literal notranslate"><span class="pre">ClientUIFunctions</span></code></a>.</p>
</section>
</section>
<section id="initializing">
<h2>Initializing<a class="headerlink" href="#initializing" title="Link to this heading"></a></h2>
<p>When starting the client, initialize the Client Lib with</p>
<dl class="c function">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_initClientLib</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="3dsound.html#c.ClientUIFunctions" title="ClientUIFunctions"><span class="n"><span class="pre">ClientUIFunctions</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">functionPointers</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">ClientUIFunctionsRare</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">functionRarePointers</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">usedLogTypes</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">logFileFolder</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">resourcesFolder</span></span><span class="sig-paren">)</span><br /></dt>
<dd><p>initializes the client library and defines callback functions </p>
<p>This is the first function you need to call, before this all calls to the client library will fail. In this call you will also set the functions you would like to have called when certain changes happen on the client side as well as on connected servers.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>functionPointers</strong> – defines which functions in your code are to be called on specific events. Zero initialize it and assign the desired function to call to the respective members of the struct </p></li>
<li><p><strong>functionRarePointers</strong> – similar to the functionPointers parameter. These are not available in the SDK, so SDK users should pass a nullptr here. </p></li>
<li><p><strong>usedLogTypes</strong> – a combination of values from the <a class="reference internal" href="../enumerations.html#logtypes_8h_1a0e4c244f5254ca12ffeadcaf83e225b4"><span class="std std-ref">LogTypes</span></a> enum. Specifies which type(s) of logging you would like to use. </p></li>
<li><p><strong>logFileFolder</strong> – path in which to create log files </p></li>
<li><p><strong>resourcesFolder</strong> – path to the directory in which the soundbackends folder is located. Required to be able to load the sound backends and process audio. </p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>This function must not be called more than once.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Logging to console can slow down the application on Windows. Hence
we do not recommend to log to the console on Windows other than in
debug builds.</p>
</div>
</section>
<section id="querying-the-library-version">
<h2>Querying the library version<a class="headerlink" href="#querying-the-library-version" title="Link to this heading"></a></h2>
<p>The complete Client Lib version string can be queried with</p>
<dl class="c function">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_getClientLibVersion</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><br /></dt>
<dd><p>Get the version string of the client library. </p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>result</strong> – Pointer to a char* variable that the client library will allocate memory for. If the return value is ERROR_ok the memory was allocated and the variable pointed to will contain the client library version. You need to free the variable pointed to by using <a class="reference internal" href="../client_api.html#clientlib_8h_1a783cbda7046acfc0173c669821702619"><span class="std std-ref">ts3client_freeMemory</span></a></p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<p>To get only the version number, which is a part of the complete version
string, as numeric value use</p>
<dl class="c function">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_getClientLibVersionNumber</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">result</span></span><span class="sig-paren">)</span><br /></dt>
<dd><p>Get the version number of the client library. </p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>result</strong> – Pointer to a variable to store the client library version number into </p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<section id="examples">
<h3>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h3>
<p>Query the client lib version:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="linenos">2</span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">version</span><span class="p">;</span>
<span class="linenos">3</span><span class="n">error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ts3client_getClientLibVersion</span><span class="p">(</span><span class="o">&amp;</span><span class="n">version</span><span class="p">);</span>
<span class="linenos">4</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">error</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="linenos">5</span><span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Error querying clientlib version: %d</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">error</span><span class="p">);</span>
<span class="linenos">6</span><span class="w"> </span><span class="k">return</span><span class="p">;</span>
<span class="linenos">7</span><span class="p">}</span>
<span class="linenos">8</span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Client library version: %s</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">version</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Print version */</span>
<span class="linenos">9</span><span class="n">ts3client_freeMemory</span><span class="p">(</span><span class="n">version</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Release string */</span>
</pre></div>
</div>
<p>To only get the version number:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos">1</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="linenos">2</span><span class="n">uint64</span><span class="w"> </span><span class="n">version</span><span class="p">;</span>
<span class="linenos">3</span><span class="n">error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ts3client_getClientLibVersionNumber</span><span class="p">(</span><span class="o">&amp;</span><span class="n">version</span><span class="p">);</span>
<span class="linenos">4</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">error</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="linenos">5</span><span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Error querying clientlib version number: %d</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">error</span><span class="p">);</span>
<span class="linenos">6</span><span class="w"> </span><span class="k">return</span><span class="p">;</span>
<span class="linenos">7</span><span class="p">}</span>
<span class="linenos">8</span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Client library version number: %ld</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">version</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Print version */</span>
</pre></div>
</div>
</section>
</section>
<section id="shutting-down">
<h2>Shutting down<a class="headerlink" href="#shutting-down" title="Link to this heading"></a></h2>
<p>Before exiting the client application, you should disconnect from any
servers you’re connected to (<a class="reference internal" href="connections.html#c.ts3client_stopConnection" title="ts3client_stopConnection"><code class="xref c c-func docutils literal notranslate"><span class="pre">ts3client_stopConnection()</span></code></a>) and destroy
the connection handler (<a class="reference internal" href="connections.html#c.ts3client_destroyServerConnectionHandler" title="ts3client_destroyServerConnectionHandler"><code class="xref c c-func docutils literal notranslate"><span class="pre">ts3client_destroyServerConnectionHandler()</span></code></a>).
After that the Client Lib should be shut down using</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.ts3client_destroyClientLib">
<span class="target" id="clientlib_8h_1ac196aa5fba17c2da16ca4d0a4c036977"></span><span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_destroyClientLib</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.ts3client_destroyClientLib" title="Link to this definition"></a><br /></dt>
<dd><p>destroys the client library. Must not be called from within a callback. </p>
<p>This is the last function to call, after calling this function you will no longer be able to use client library functions.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<p>Any call to client lib functions after shutting down has undefined results.</p>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Never destroy the client lib from within a callback. This might
result in segmentation fault.</p>
</div>
</section>
<section id="error-handling">
<h2>Error handling<a class="headerlink" href="#error-handling" title="Link to this heading"></a></h2>
<p>Each Client Lib function returns either <a class="reference internal" href="../errors.html#c.Ts3ErrorType.ERROR_ok" title="Ts3ErrorType.ERROR_ok"><code class="xref c c-enumerator docutils literal notranslate"><span class="pre">ERROR_ok</span></code></a>
on success or an error value as defined in <a class="reference internal" href="../errors.html#c.Ts3ErrorType" title="Ts3ErrorType"><code class="xref c c-enum docutils literal notranslate"><span class="pre">Ts3ErrorType</span></code></a> 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 <code class="docutils literal notranslate"><span class="pre">ERROR_&lt;group&gt;_&lt;error&gt;</span></code>, for example
<a class="reference internal" href="../errors.html#c.Ts3ErrorType.ERROR_client_invalid_id" title="Ts3ErrorType.ERROR_client_invalid_id"><code class="xref c c-enumerator docutils literal notranslate"><span class="pre">ERROR_client_invalid_id</span></code></a>.</p>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>Client Lib functions returning C-strings or arrays dynamically
allocate memory which has to be freed by the caller using
<a class="reference internal" href="../client_api.html#c.ts3client_freeMemory" title="ts3client_freeMemory"><code class="xref c c-func docutils literal notranslate"><span class="pre">ts3client_freeMemory()</span></code></a>. It is important to <strong>only</strong>
access and release the memory if the function returned <a class="reference internal" href="../errors.html#c.Ts3ErrorType.ERROR_ok" title="ERROR_ok"><code class="xref c c-enumerator docutils literal notranslate"><span class="pre">ERROR_ok</span></code></a>.
Should the function return an error, the result variable is
uninitialized, so freeing or accessing it could crash the
application.</p>
</div>
<p>See the section <a class="reference internal" href="#c-calling"><span class="std std-ref">Calling Client Lib functions</span></a> for
additional notes and examples.</p>
<p>A printable error string for a specific error code can be queried with</p>
<dl class="c function">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_getErrorMessage</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">errorCode</span></span>, <span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">error</span></span><span class="sig-paren">)</span><br /></dt>
<dd><p>Retrieve human readable description for an error code. </p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>errorCode</strong> – the error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum to retrieve the description for </p></li>
<li><p><strong>error</strong> – address of a variable to receive a c string with the error description. Memory is allocated by the client lib and must be freed by caller using <a class="reference internal" href="../client_api.html#clientlib_8h_1a783cbda7046acfc0173c669821702619"><span class="std std-ref">ts3client_freeMemory</span></a></p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<section id="error-callback">
<h3>Error callback<a class="headerlink" href="#error-callback" title="Link to this heading"></a></h3>
<p>In addition to actively querying errors like above, error codes can be
sent by the server to the client through the following callback</p>
<dl class="c struct">
<dt class="sig sig-object c">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ClientUIFunctions</span></span></span><br /></dt>
<dd><p>Defines available callbacks that you can receive. </p>
<p>Set the members of this struct to a function to call when the specific event happens. </p>
<div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-members">Public Members</p>
<dl class="c var">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">onServerErrorEvent</span></span></span><span class="p"><span class="pre">)</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">serverConnectionHandlerID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">errorMessage</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">error</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">returnCode</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">extraMessage</span></span><span class="p"><span class="pre">)</span></span><br /></dt>
<dd><p>called after an action was performed by us. Tells whether the action was successful or which error occurred. </p>
<dl class="field-list simple">
<dt class="field-odd">Param serverConnectionHandlerID<span class="colon">:</span></dt>
<dd class="field-odd"><p>specifies on which connection the callback was called </p>
</dd>
<dt class="field-even">Param errorMessage<span class="colon">:</span></dt>
<dd class="field-even"><p>utf8 encoded c string describing the error </p>
</dd>
<dt class="field-odd">Param error<span class="colon">:</span></dt>
<dd class="field-odd"><p>the error code the action finished with. One of the values from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum. </p>
</dd>
<dt class="field-even">Param returnCode<span class="colon">:</span></dt>
<dd class="field-even"><p>a c string identifying the action that caused this error. This is the same string given as returnCode to function calls that request an action on the server </p>
</dd>
<dt class="field-odd">Param extraMessage<span class="colon">:</span></dt>
<dd class="field-odd"><p>utf8 encoded c string containing additional information if available. </p>
</dd>
</dl>
</dd></dl>
</div>
</dd></dl>
</section>
<section id="id1">
<h3>Examples<a class="headerlink" href="#id1" title="Link to this heading"></a></h3>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="linenos"> 2</span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">welcomeMsg</span><span class="p">;</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="n">error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ts3client_getServerVariableAsString</span><span class="p">(</span><span class="n">serverConnectionHandlerID</span><span class="p">,</span><span class="w"> </span><span class="n">VIRTUALSERVER_WELCOMEMESSAGE</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">welcomeMsg</span><span class="p">);</span>
<span class="linenos"> 5</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">error</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="cm">/* Use welcomeMsg... */</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="n">ts3client_freeMemory</span><span class="p">(</span><span class="n">welcomeMsg</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Release memory *only* if function did not return an error */</span>
<span class="linenos"> 8</span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span>
<span class="linenos"> 9</span><span class="w"> </span><span class="cm">/* Handle error */</span>
<span class="linenos">10</span><span class="w"> </span><span class="cm">/* Do not access or release welcomeMessage, the variable is undefined */</span>
<span class="linenos">11</span><span class="p">}</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">error</span><span class="p">;</span>
<span class="linenos"> 2</span><span class="n">anyID</span><span class="w"> </span><span class="n">myID</span><span class="p">;</span>
<span class="linenos"> 3</span>
<span class="linenos"> 4</span><span class="n">error</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ts3client_getClientID</span><span class="p">(</span><span class="n">scHandlerID</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">myID</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Calling some Client Lib function */</span>
<span class="linenos"> 5</span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">error</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="linenos"> 6</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">errorMsg</span><span class="p">;</span>
<span class="linenos"> 7</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">ts3client_getErrorMessage</span><span class="p">(</span><span class="n">error</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">errorMsg</span><span class="p">)</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">ERROR_ok</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* Query printable error */</span>
<span class="linenos"> 8</span><span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">&quot;Error querying client ID: %s</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">errorMsg</span><span class="p">);</span>
<span class="linenos"> 9</span><span class="w"> </span><span class="n">ts3client_freeMemory</span><span class="p">(</span><span class="n">errorMsg</span><span class="p">);</span><span class="w"> </span><span class="cm">/* Release memory */</span>
<span class="linenos">10</span><span class="w"> </span><span class="p">}</span>
<span class="linenos">11</span><span class="p">}</span>
</pre></div>
</div>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="intro.html" class="btn btn-neutral float-left" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="connections.html" class="btn btn-neutral float-right" title="Managing server connections" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2020, TeamSpeak Systems GmbH.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>