34 lines
10 KiB
HTML
34 lines
10 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Initializing</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="ar01s04.html" title="Calling Client Lib functions"><link rel="next" href="ar01s06.html" title="Querying the library version"></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">Initializing</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s04.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="ar01s06.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="initializing"></a>Initializing</h2></div></div></div><p>When starting the client, initialize the Client Lib with a call to
|
||
</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_initClientLib</b>(</code></td><td><var class="pdparam">functionPointers</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">functionRarePointers</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">usedLogTypes</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">logFileFolder</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">resourcesFolder</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>const struct ClientUIFunctions* <var class="pdparam">functionPointers</var></code>;<br><code>const struct ClientUIFunctionsRare* <var class="pdparam">functionRarePointers</var></code>;<br><code>int <var class="pdparam">usedLogTypes</var></code>;<br><code>const char* <var class="pdparam">logFileFolder</var></code>;<br><code>const char* <var class="pdparam">resourcesFolder</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835435211392"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>functionPointers</code></em></p><p>Callback function pointers. See <a class="link" href="ar01s05.html#callback" title="The callback mechanism">below</a>.</p></li><li><p><em class="parameter"><code>functionRarePointers</code></em></p><p>Unused by SDK, pass NULL.</p></li><li><p><em class="parameter"><code>usedLogTypes</code></em></p><p>Defines the log output types. The Client Lib can output log messages (called by <a class="link" href="ar01s12.html" title="Logging"><code class="function">ts3client_logMessage</code></a>) to a file (located in the <code class="filename">logs</code> directory relative to the client executable), to stdout or to user defined callbacks. If user callbacks are activated, the <a class="link" href="ar01s12.html#userlogging" title="User-defined logging"><code class="function">onUserLoggingMessageEvent</code></a> event needs to be implemented.</p><p>Available values are defined by the enum <span class="structname">LogTypes</span> (see <code class="filename">public_definitions.h</code>):</p><a class="indexterm" name="idm44835435108544"></a><pre class="programlisting">enum LogTypes {
|
||
LogType_NONE = 0x0000,
|
||
LogType_FILE = 0x0001,
|
||
LogType_CONSOLE = 0x0002,
|
||
LogType_USERLOGGING = 0x0004,
|
||
LogType_NO_NETLOGGING = 0x0008,
|
||
LogType_DATABASE = 0x0010,
|
||
};</pre><p>Multiple log types can be combined with a binary OR. If only <em class="structfield"><code>LogType_NONE</code></em> is used, local logging is disabled.</p><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>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></td></tr></table></div><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><em class="structfield"><code>LogType_NO_NETLOGGING</code></em> is no longer used. Previously this controlled if the Client Lib would send warning, error and critical log entries to a webserver for analysis. As netlogging does not occur anymore, this flag has no effect anymore.</p><p>LogType_DATABASE has no effect in the Client Lib, this is only used by the server.</p></td></tr></table></div></li><li><p><em class="parameter"><code>logFileFolder</code></em></p><p>If file logging is used, this defines the location where the logs are written to. Pass NULL for the default behaviour, which is to use a folder called <code class="filename">logs</code> in the current working directory.</p><p><em class="parameter"><code>resourcesFolder</code></em></p><p>Resource path pointing to the directory where the soundbackends folder is located. Required so your application finds the sound backend shared libraries. This should usually point to the root or bin directory of your application, depending where the soundbackends directory is located.</p></li></ul></div><p>Returns <em class="structfield"><code>ERROR_ok</code></em> on success, otherwise an error code as defined in <code class="filename">public_errors.h</code>.</p><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>This function must not be called more than once.</p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="callback"></a>The callback mechanism</h3></div></div></div><p>The communication from Client Lib to Client UI takes place using callbacks<a class="indexterm" name="idm44835435096608"></a>. The Client UI has to define a series of function pointers using the struct <span class="structname">ClientUIFunctions</span> (see <code class="filename">clientlib.h</code>). These callbacks are used to forward any incoming server actions to the Client UI for further processing.</p><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>All the clientlib callbacks are asynchronous, except for the sound callbacks which allow to directly manipulate the sound buffer.</p></td></tr></table></div><p>A callback example in C:</p><pre class="programlisting">static void my_onConnectStatusChangeEvent_Callback(uint64 serverConnectionHandlerID,
|
||
int newStatus,
|
||
int errorNumber) {
|
||
/* Implementation */
|
||
}</pre><p>C++ developers can also use static member functions for the callbacks.</p><p>Before calling <code class="function">ts3client_initClientLib</code>, create an instance of struct ClientUIFunctions, initialize all function pointers with NULL and assign the structs function pointers to your callback functions:
|
||
</p><pre class="programlisting">unsigned int error;
|
||
|
||
/* Create struct */
|
||
ClientUIFunctions clUIFuncs;
|
||
|
||
/* Initialize all function pointers with NULL */
|
||
memset(&clUIFuncs, 0, sizeof(struct ClientUIFunctions));
|
||
|
||
/* Assign those function pointers you implemented */
|
||
clUIFuncs.onConnectStatusChangeEvent = my_onConnectStatusChangeEvent_Callback;
|
||
clUIFuncs.onNewChannelEvent = my_onNewChannelEvent_Callback;
|
||
(...)
|
||
|
||
/* Initialize client lib with callback function pointers */
|
||
error = ts3client_initClientLib(&clUIFuncs, NULL, LogType_FILE | LogType_CONSOLE);
|
||
if(error != ERROR_ok) {
|
||
printf("Error initializing clientlib: %d\n", error);
|
||
(...)
|
||
}</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>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 crash when trying to calling them.</p></td></tr></table></div><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>All callbacks used in the SDK are found in the struct <span class="structname">ClientUIFunctions</span> (see <code class="filename">public_definitions.h</code>). Callbacks bundled in the struct <span class="structname">ClientUIFunctionsRare</span> are not used by the SDK. These callbacks were split in a separate structs to avoid polluting the SDK headers with code used only internally.</p></td></tr></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s04.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="ar01s06.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Calling Client Lib functions </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"> Querying the library version</td></tr></table></div></body></html>
|