50 lines
14 KiB
HTML
50 lines
14 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Server information</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="ar01s22.html" title="Retrieve and store information"><link rel="prev" href="ar01s22s02s02.html" title="Channel sorting"><link rel="next" href="ar01s23.html" title="Interacting with the 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">Server information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s22s02s02.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Retrieve and store information</th><td width="20%" align="right"> <a accesskey="n" href="ar01s23.html"><img src="images/next.png" alt="Next"></a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="serverinfo"></a>Server information</h3></div></div></div><p>Similar to reading client and channel data, server information can be queried with</p><p>
|
||
<a name="getservervarasint"></a>
|
||
</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_getServerVariableAsInt</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">flag</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>VirtualServerProperties <var class="pdparam">flag</var></code>;<br><code>int* <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433613520"></a>
|
||
</p><p>
|
||
</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_getServerVariableAsUInt64</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">flag</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>VirtualServerProperties <var class="pdparam">flag</var></code>;<br><code>uint64* <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433608656"></a>
|
||
</p><p>
|
||
<a name="getservervarasstring"></a>
|
||
</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_getServerVariableAsString</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">flag</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>VirtualServerProperties <var class="pdparam">flag</var></code>;<br><code>char** <var class="pdparam">result</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433603264"></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 the virtual server property is queried.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client whose property is queried.</p></li><li><p><em class="parameter"><code>flag</code></em></p><p>Virtual server propery to query, see below.</p></li><li><p><em class="parameter"><code>result</code></em></p><p>Address of a variable which receives the result value as int, uint64 or string, depending on which function is used. In case of a string, memory must be released using <a class="link" href="ar01s28.html#freememory"><code class="function">ts3client_freeMemory</code></a>, unless an error occured.</p><p>The returned type <span class="type">uint64</span> is defined as <span class="type">__int64</span> on Windows and <span class="type">uint64_t</span> on Linux and Mac OS X. See the header <code class="filename">public_definitions.h</code>. This function is currently only used for the flag <em class="structfield"><code>VIRTUALSERVER_UPTIME</code></em>.</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>. For the string version: If an error has occured, the result string is uninitialized and must not be released.</p><p>The parameter <em class="parameter"><code>flag</code></em> specifies the type of queried information. It is defined by the enum <span class="structname">VirtualServerProperties</span><a class="indexterm" name="idm44835433588272"></a>:</p><pre class="programlisting">enum VirtualServerProperties {
|
||
VIRTUALSERVER_UNIQUE_IDENTIFIER = 0, //available when connected, can be used to identify this particular
|
||
//server installation
|
||
VIRTUALSERVER_NAME, //available and always up-to-date when connected
|
||
VIRTUALSERVER_WELCOMEMESSAGE, //available when connected, not updated while connected
|
||
VIRTUALSERVER_PLATFORM, //available when connected
|
||
VIRTUALSERVER_VERSION, //available when connected
|
||
VIRTUALSERVER_MAXCLIENTS, //only available on request (=> requestServerVariables), stores the
|
||
//maximum number of clients that may currently join the server
|
||
VIRTUALSERVER_PASSWORD, //not available to clients, the server password
|
||
VIRTUALSERVER_CLIENTS_ONLINE, //only available on request (=> requestServerVariables),
|
||
VIRTUALSERVER_CHANNELS_ONLINE, //only available on request (=> requestServerVariables),
|
||
VIRTUALSERVER_CREATED, //available when connected, stores the time when the server was created
|
||
VIRTUALSERVER_UPTIME, //only available on request (=> requestServerVariables), the time
|
||
//since the server was started
|
||
VIRTUALSERVER_CODEC_ENCRYPTION_MODE, //available and always up-to-date when connected
|
||
VIRTUALSERVER_ENCRYPTION_CIPHERS, //SDK only: list of ciphers that can be used for encryption
|
||
VIRTUALSERVER_ENDMARKER,
|
||
};</pre><div class="itemizedlist"><ul type="disc"><li><p><em class="structfield"><code>VIRTUALSERVER_UNIQUE_IDENTIFIER</code></em></p><p>Unique ID for this virtual server. Stays the same after restarting the server application. Always available when connected.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_NAME</code></em></p><p>Name of this virtual server. Always available when connected.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_WELCOMEMESSAGE</code></em></p><p>Optional welcome message sent to the client on login. This value should be queried by the client after connection has been established, it is <span class="emphasis"><em>not</em></span> updated afterwards.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_PLATFORM</code></em></p><p>Operating system used by this server. Always available when connected.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_VERSION</code></em></p><p>Application version of this server. Always available when connected.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_MAXCLIENTS</code></em></p><p>Defines maximum number of clients which may connect to this server. Needs to be requested using <code class="function">ts3client_requestServerVariables</code>.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_PASSWORD</code></em></p><p>Optional password of this server. Not available to clients.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_CLIENTS_ONLINE</code></em></p><p><em class="structfield"><code>VIRTUALSERVER_CHANNELS_ONLINE</code></em></p><p>Number of clients and channels currently on this virtual server. Needs to be requested using <code class="function">ts3client_requestServerVariables</code>.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_CREATED</code></em></p><p>Time when this virtual server was created. Always available when connected.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_UPTIME</code></em></p><p>Uptime of this virtual server. Needs to be requested using <code class="function">ts3client_requestServerVariables</code>.</p></li><li><p><em class="structfield"><code>VIRTUALSERVER_CODEC_ENCRYPTION_MODE</code></em></p><p>Defines if voice data encryption is configured per channel, globally forced on or globally forced off for this virtual server. The default behaviour is configure per channel, in this case modifying the channel property <em class="structfield"><code>CHANNEL_CODEC_IS_UNENCRYPTED</code></em> defines voice data encryption of individual channels.</p><p>Virtual server encryption mode can be set to the following parameters:
|
||
</p><pre class="programlisting">enum CodecEncryptionMode {
|
||
CODEC_ENCRYPTION_PER_CHANNEL = 0,
|
||
CODEC_ENCRYPTION_FORCED_OFF,
|
||
CODEC_ENCRYPTION_FORCED_ON,
|
||
};</pre><p>
|
||
</p><p>This property is always available when connected.</p><a class="indexterm" name="idm44835433565280"></a></li></ul></div><div class="literallayout"><p><br>
|
||
</p></div><p>Example code checking the number of clients online, obviously an integer value:
|
||
</p><pre class="programlisting">int clientsOnline;
|
||
|
||
if(ts3client_getServerVariableAsInt(scHandlerID, VIRTUALSERVER_CLIENTS_ONLINE, &clientsOnline) == ERROR_ok)
|
||
printf("There are %d clients online\n", clientsOnline);</pre><div class="literallayout"><p><br>
|
||
</p></div><p>A client can request refreshing the server information 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_requestServerVariables</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433559920"></a></p><p>The following event informs the client when the requested information is available:
|
||
</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">onServerUpdatedEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433556528"></a></p><div class="literallayout"><p><br>
|
||
</p></div><p>The following event notifies the client when virtual server information has been edited:
|
||
</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">onServerEditedEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">editerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">editerName</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">editerUniqueIdentifier</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">editerID</var></code>;<br><code>const char* <var class="pdparam">editerName</var></code>;<br><code>const char* <var class="pdparam">editerUniqueIdentifier</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433550640"></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 which virtual server information has been changed.</p></li><li><p><em class="parameter"><code>editerID</code></em></p><p>ID of the client who edited the information. If zero, the server is the editor.</p></li><li><p><em class="parameter"><code>editerName</code></em></p><p>Name of the client who edited the information.</p></li><li><p><em class="parameter"><code>editerUniqueIdentifier</code></em></p><p>Unique ID of the client who edited the information.</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="ar01s22s02s02.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ar01s22.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s23.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Channel sorting </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"> Interacting with the server</td></tr></table></div></body></html>
|