63 lines
22 KiB
HTML
63 lines
22 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Connecting to a server</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="ar01s08.html" title="Managing server connection handlers"><link rel="next" href="ar01s10.html" title="Disconnecting from a server"></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">Connecting to a server</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s08.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="ar01s10.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="connect"></a>Connecting to a server</h2></div></div></div><p>To connect to a server, a client application is required to request an identity from the Client Lib. This string should be requested only once and then locally stored in the applications configuration. The next time the application connects to a server, the identity should be read from the configuration and reused again.
|
||
</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_createIdentity</b>(</code></td><td><var class="pdparam">result</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>char** <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835435037440"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>result</code></em></p><p>Address of a variable that receives the identity string, encoded in UTF-8.</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>. If an error occured, the result string is uninitialized and must not be accessed.</p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/caution.png"></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p>The result string must be released using <a class="link" href="ar01s28.html#freememory"><code class="function">ts3client_freeMemory</code></a>. If an error has occured, the result string is uninitialized and must not be released.</p></td></tr></table></div><div class="literallayout"><p><br>
|
||
</p></div><p>Once a server connection handler has been <a class="link" href="ar01s08.html" title="Managing server connection handlers">spawned</a> and an identity is available, connect to a TeamSpeak 3 server 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_startConnection</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">identity</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">ip</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">port</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">nickname</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">defaultChannelArray</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">defaultChannelPassword</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">serverPassword</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">identity</var></code>;<br><code>const char* <var class="pdparam">ip</var></code>;<br><code>unsigned int <var class="pdparam">port</var></code>;<br><code>const char* <var class="pdparam">nickname</var></code>;<br><code>const char** <var class="pdparam">defaultChannelArray</var></code>;<br><code>const char* <var class="pdparam">defaultChannelPassword</var></code>;<br><code>const char* <var class="pdparam">serverPassword</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835435023616"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>Unique identifier for this server connection. Created with <code class="function">ts3client_spawnNewServerConnectionHandler</code></p></li><li><p><em class="parameter"><code>identity</code></em></p><p>The clients identity. This string has to be created by calling <code class="function">ts3client_createIdentity</code>. Please note an application should create the identity only once, store the string locally and reuse it for future connections.</p></li><li><p><em class="parameter"><code>ip</code></em></p><p>Hostname or IP of the TeamSpeak 3 server.</p><p>If you pass a hostname instead of an IP, the Client Lib will try to resolve it to an IP, but the function may block for an unusually long period of time while resolving is taking place. If you are relying on the function to return quickly, we recommend to resolve the hostname yourself (e.g. asynchronously) and then call <code class="function">ts3client_startConnection</code> with the IP instead of the hostname.</p></li><li><p><em class="parameter"><code>port</code></em></p><p>UDP port of the TeamSpeak 3 server, by default 9987. TeamSpeak 3 uses UDP. Support for TCP might be added in the future.</p></li><li><p><em class="parameter"><code>nickname</code></em></p><p>On login, the client attempts to take this nickname on the connected server. Note this is not necessarily the actually assigned nickname, as the server can modifiy the nickname ("gandalf_1" instead the requested "gandalf") or refuse blocked names.</p></li><li><p><em class="parameter"><code>defaultChannelArray</code></em></p><p>String array defining the path to a channel on the TeamSpeak 3 server. If the channel exists and the user has sufficient rights and supplies the correct password if required, the channel will be joined on login.</p><p>To define the path to a subchannel of arbitrary level, create an array of channel names detailing the position of the default channel (e.g. "grandparent", "parent", "mydefault", ""). The array is terminated with a empty string.</p><p>Pass NULL to join the servers default channel.</p></li><li><p><em class="parameter"><code>defaultChannelPassword</code></em></p><p>Password for the default channel. Pass an empty string if no password is required or no default channel is specified.</p></li><li><p><em class="parameter"><code>serverPassword</code></em></p><p>Password for the server. Pass an empty string if the server does not require a password.</p></li></ul></div><p>All strings need to be encoded in UTF-8 format.</p><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>. When trying to connect with an invalid identity, the Client Lib will set the error <em class="structfield"><code>ERROR_client_could_not_validate_identity</code></em>.</p><div class="literallayout"><p><br>
|
||
</p></div><p>There is an alternative convinience function to start the connection which takes a channelID as parameter for the default channel instead of a channel name string array.
|
||
</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_startConnectionWithChannelID</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">identity</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">ip</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">port</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">nickname</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">defaultChannelId</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">defaultChannelPassword</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">serverPassword</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">identity</var></code>;<br><code>const char* <var class="pdparam">ip</var></code>;<br><code>unsigned int <var class="pdparam">port</var></code>;<br><code>const char* <var class="pdparam">nickname</var></code>;<br><code>uint64 <var class="pdparam">defaultChannelId</var></code>;<br><code>const char* <var class="pdparam">defaultChannelPassword</var></code>;<br><code>const char* <var class="pdparam">serverPassword</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434996048"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>Unique identifier for this server connection. Created with <code class="function">ts3client_spawnNewServerConnectionHandler</code></p></li><li><p><em class="parameter"><code>identity</code></em></p><p>The clients identity. This string has to be created by calling <code class="function">ts3client_createIdentity</code>. Please note an application should create the identity only once, store the string locally and reuse it for future connections.</p></li><li><p><em class="parameter"><code>ip</code></em></p><p>Hostname or IP of the TeamSpeak 3 server.</p><p>If you pass a hostname instead of an IP, the Client Lib will try to resolve it to an IP, but the function may block for an unusually long period of time while resolving is taking place. If you are relying on the function to return quickly, we recommend to resolve the hostname yourself (e.g. asynchronously) and then call <code class="function">ts3client_startConnection</code> with the IP instead of the hostname.</p></li><li><p><em class="parameter"><code>port</code></em></p><p>UDP port of the TeamSpeak 3 server, by default 9987. TeamSpeak 3 uses UDP. Support for TCP might be added in the future.</p></li><li><p><em class="parameter"><code>nickname</code></em></p><p>On login, the client attempts to take this nickname on the connected server. Note this is not necessarily the actually assigned nickname, as the server can modifiy the nickname ("gandalf_1" instead the requested "gandalf") or refuse blocked names.</p></li><li><p><em class="parameter"><code>defaultChannelID</code></em></p><p>Specifies ID of the channel on the TeamSpeak server we want to connect to. This is an alternative way to define the channel by ID instead of channel path as in <code class="function">ts3client_startConnection</code>. If the specified channel does no longer exist or if the channel password is incorrect, the user will be connected to the default channel of the TeamSpeak server.</p></li><li><p><em class="parameter"><code>defaultChannelPassword</code></em></p><p>Password for the default channel. Pass an empty string if no password is required or no default channel is specified.</p></li><li><p><em class="parameter"><code>serverPassword</code></em></p><p>Password for the server. Pass an empty string if the server does not require a password.</p></li></ul></div><div class="literallayout"><p><br>
|
||
</p></div><p>Example code to request a connection to a TeamSpeak 3 server:</p><pre class="programlisting">unsigned int error;
|
||
uint64 scHandlerID;
|
||
char* identity;
|
||
|
||
error = ts3client_spawnNewServerConnectionHandler(&scHandlerID);
|
||
if(error != ERROR_ok) {
|
||
printf("Error spawning server conection handler: %d\n", error);
|
||
return;
|
||
}
|
||
|
||
error = ts3client_createIdentity(&identity); /* Application should store and reuse the identity */
|
||
if(error != ERROR_ok) {
|
||
printf("Error creating identity: %d\n", error);
|
||
return;
|
||
}
|
||
|
||
error = ts3client_startConnection(scHandlerID,
|
||
identity
|
||
"my-teamspeak-server.com",
|
||
9987,
|
||
"Gandalf",
|
||
NULL, // Join servers default channel
|
||
"", // Empty default channel password
|
||
"secret"); // Server password
|
||
if(error != ERROR_ok) {
|
||
(...)
|
||
}
|
||
ts3client_freeMemory(identity); /* Don't need this anymore */</pre><div class="literallayout"><p><br>
|
||
</p></div><p>After calling <code class="function">ts3client_startConnection</code>, the client will be informed of the connection status changes by the callback</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">onConnectStatusChangeEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">newStatus</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">errorNumber</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>int <var class="pdparam">newStatus</var></code>;<br><code>int <var class="pdparam">errorNumber</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434970288"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>newStatus</code></em></p><p>The new connect state as defined by the enum <span class="structname">ConnectStatus</span><a class="indexterm" name="idm44835434967632"></a>:</p><a name="connectstatus"></a><pre class="programlisting">enum ConnectStatus {
|
||
STATUS_DISCONNECTED = 0, //There is no activity to the server, this is the default value
|
||
STATUS_CONNECTING, //We are trying to connect, we haven't got a clientID yet, we
|
||
//haven't been accepted by the server
|
||
STATUS_CONNECTED, //The server has accepted us, we can talk and hear and we got a
|
||
//clientID, but we don't have the channels and clients yet, we
|
||
//can get server infos (welcome msg etc.)
|
||
STATUS_CONNECTION_ESTABLISHING,//we are CONNECTED and we are visible
|
||
STATUS_CONNECTION_ESTABLISHED, //we are CONNECTED and we have the client and channels available
|
||
};</pre></li><li><p><em class="parameter"><code>errorNumber</code></em></p><p>Should be <em class="structfield"><code>ERROR_ok</code></em> (zero) when connecting</p></li></ul></div><p>
|
||
While connecting, the states will switch through the values <em class="structfield"><code>STATUS_CONNECTING</code></em>, <em class="structfield"><code>STATUS_CONNECTED</code></em> and <em class="structfield"><code>STATUS_CONNECTION_ESTABLISHED</code></em>. Once the state <em class="structfield"><code>STATUS_CONNECTED</code></em> has been reached, there the server welcome message is available, which can be queried by the client:</p><div class="itemizedlist"><ul type="disc"><li><p>Welcome message<a class="indexterm" name="idm44835434959920"></a></p><p>Query the server variable <em class="structfield"><code>VIRTUALSERVER_WELCOMEMESSAGE</code></em> for the message text using the function <a class="link" href="ar01s22s03.html#getservervarasstring"><code class="function">ts3client_getServerVariableAsString</code></a>:</p><pre class="programlisting">char* welcomeMsg;
|
||
if(ts3client_getServerVariableAsString(serverConnectionHandlerID, VIRTUALSERVER_WELCOMEMESSAGE, &welcomeMsg)
|
||
!= ERROR_ok) {
|
||
printf("Error getting server welcome message: %d\n", error);
|
||
return;
|
||
}
|
||
print("Welcome message: %s\n", welcomeMsg); /* Display message */
|
||
ts3client_freeMemory(welcomeMsg); /* Release memory */</pre></li></ul></div><div class="literallayout"><p><br>
|
||
</p></div><p>To check if a connection to a given server connection handler is established, call:
|
||
</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_getConnectionStatus</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">result</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>int* <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434952576"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler of which the connection state is checked.</p></li><li><p><em class="parameter"><code>result</code></em></p><p>Address of a variable that receives the result: 1 - Connected, 0 - Not connected.</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="literallayout"><p><br>
|
||
</p></div><p>After the state <em class="structfield"><code>STATUS_CONNECTED</code></em> has been reached, the client is assigned an ID which identifies the client on this server.<a class="indexterm" name="idm44835434945504"></a> This ID 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_getClientID</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">result</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>anyID* <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835434942208"></a></p><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>ID of the server connection handler on which we are querying the own client ID.</p></li><li><p><em class="parameter"><code>result</code></em></p><p>Address of a variable that receives the client ID. Client IDs start with the value 1.</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="literallayout"><p><br>
|
||
</p></div><p>After connection has been established, all current channels on the server are announced to the client. This happens with delays to avoid a flood of information after connecting. The client is informed about the existance of each channel with the following event:</p><a name="onnewchannelevent"></a><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">onNewChannelEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelParentID</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>uint64 <var class="pdparam">channelID</var></code>;<br><code>uint64 <var class="pdparam">channelParentID</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835434931408"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>The server connection handler ID.</p></li><li><p><em class="parameter"><code>channelID</code></em></p><p>The ID of the announced channel.</p></li><li><p><em class="parameter"><code>channelParentID</code></em></p><p>ID of the parent channel.</p></li></ul></div><p>Channel IDs start with the value 1.</p><p>The order in which channels are announced by <code class="function">onNewChannelEvent</code> is defined by the channel order as explained in the chapter <a class="link" href="ar01s22s02s02.html" title="Channel sorting">Channel sorting</a>.</p><p>All clients currently logged to the server are announced after connecting with the callback <a class="link" href="ar01s23.html#onclientmove"><code class="function">onClientMoveEvent</code></a>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s08.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="ar01s10.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Managing server connection handlers </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"> Disconnecting from a server</td></tr></table></div></body></html>
|