rogo/TS_WIFILED
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
Files
f36bfab5aa27b08fbeb33f070951a4078d4de418
TS_WIFILED/docs/client_html/ar01s22.html
rogo f36bfab5aa init
2020-04-04 17:21:07 +02:00

144 lines
38 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Retrieve and store 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="index.html" title="TeamSpeak 3 Client SDK Developer Manual"><link rel="prev" href="ar01s21.html" title="Query available servers, channels and clients"><link rel="next" href="ar01s22s02.html" title="Channel information"></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">Retrieve and store information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s21.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="ar01s22s02.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="storedinfo"></a>Retrieve and store information</h2></div></div></div><p>The Client Lib remembers a lot of information which have been passed through previously. The data is available to be queried by a client for convinience, so the interface code doesn't need to store the same information as well. The client can in many cases also modify the stored information for further processing by the server.</p><p>All strings passed to and from the Client Lib need to be encoded in UTF-8 format.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="clientinfo"></a>Client information</h3></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ownclientinfo"></a>Information related to own client</h4></div></div></div><p>Once connection to a TeamSpeak 3 server has been established, a unique client ID is assigned by the server. 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="idm44835434002128"></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>Various information related about the own client can be checked with:</p><p>
<a name="getclientselfvarasint"></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_getClientSelfVariableAsInt</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>ClientProperties <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="idm44835433990704"></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_getClientSelfVariableAsString</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>ClientProperties <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="idm44835433985856"></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 information for the own client is requested.</p></li><li><p><em class="parameter"><code>flag</code></em></p><p>Client 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 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></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">ClientProperties</span><a class="indexterm" name="idm44835433975472"></a>:</p><a name="clientproperties"></a><pre class="programlisting">enum ClientProperties {
CLIENT_UNIQUE_IDENTIFIER = 0, //automatically up-to-date for any client "in view", can be used
//to identify this particular client installation
CLIENT_NICKNAME, //automatically up-to-date for any client "in view"
CLIENT_VERSION, //for other clients than ourself, this needs to be requested
//(=&gt; requestClientVariables)
CLIENT_PLATFORM, //for other clients than ourself, this needs to be requested
//(=&gt; requestClientVariables)
CLIENT_FLAG_TALKING, //automatically up-to-date for any client that can be heard
//(in room / whisper)
CLIENT_INPUT_MUTED, //automatically up-to-date for any client "in view", this clients
//microphone mute status
CLIENT_OUTPUT_MUTED, //automatically up-to-date for any client "in view", this clients
//headphones/speakers mute status
CLIENT_OUTPUTONLY_MUTED //automatically up-to-date for any client "in view", this clients
//headphones/speakers only mute status
CLIENT_INPUT_HARDWARE, //automatically up-to-date for any client "in view", this clients
//microphone hardware status (is the capture device opened?)
CLIENT_OUTPUT_HARDWARE, //automatically up-to-date for any client "in view", this clients
//headphone/speakers hardware status (is the playback device opened?)
CLIENT_INPUT_DEACTIVATED, //only usable for ourself, not propagated to the network
CLIENT_IDLE_TIME, //internal use
CLIENT_DEFAULT_CHANNEL, //only usable for ourself, the default channel we used to connect
//on our last connection attempt
CLIENT_DEFAULT_CHANNEL_PASSWORD,//internal use
CLIENT_SERVER_PASSWORD, //internal use
CLIENT_META_DATA, //automatically up-to-date for any client "in view", not used by
//TeamSpeak, free storage for sdk users
CLIENT_IS_MUTED, //only make sense on the client side locally, "1" if this client is
//currently muted by us, "0" if he is not
CLIENT_IS_RECORDING, //automatically up-to-date for any client "in view"
CLIENT_VOLUME_MODIFICATOR, //internal use
CLIENT_VERSION_SIGN, //internal use
CLIENT_SECURITY_HASH, //SDK only: Hash is provided by an outside source. A channel will
//use the security salt + other client data to calculate a hash,
//which must be the same as the one provided here.
CLIENT_ENCRYPTION_CIPHERS, //SDK only: list of available ciphers send to the server
CLIENT_ENDMARKER,
};</pre><div class="itemizedlist"><ul type="disc"><li><p><em class="structfield"><code>CLIENT_UNIQUE_IDENTIFIER</code></em></p><p>String: Unique ID for this client. Stays the same after restarting the application, so you can use this to identify individual users.</p></li><li><p><em class="structfield"><code>CLIENT_NICKNAME</code></em></p><p>Nickname used by the client. This value is always automatically updated for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_VERSION</code></em></p><p>Application version used by this client. Needs to be requested with <code class="function">ts3client_requestClientVariables</code> unless called on own client.</p></li><li><p><em class="structfield"><code>CLIENT_PLATFORM</code></em></p><p>Operating system used by this client. Needs to be requested with <code class="function">ts3client_requestClientVariables</code> unless called on own client.</p></li><li><p><em class="structfield"><code>CLIENT_FLAG_TALKING</code></em></p><p>Set when the client is currently sending voice data to the server. Always available for visible clients.</p><p>Note: You should query this flag for the own client using <a class="link" href="ar01s22.html#getclientselfvarasint"><code class="function">ts3client_getClientSelfVariableAsInt</code></a>.</p></li><li><p><em class="structfield"><code>CLIENT_INPUT_MUTED</code></em></p><p>Indicates the mute status of the clients capture device. Possible values are defined by the enum <span class="structname">MuteInputStatus</span>. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_OUTPUT_MUTED</code></em></p><p>Indicates the combined mute status of the clients playback and capture devices. Possible values are defined by the enum <span class="structname">MuteOutputStatus</span>. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_OUTPUTONLY_MUTED</code></em></p><p>Indicates the mute status of the clients playback device. Possible values are defined by the enum <span class="structname">MuteOutputStatus</span>. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_INPUT_HARDWARE</code></em></p><p>Set if the clients capture device is not available. Possible values are defined by the enum <span class="structname">HardwareInputStatus</span>. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_OUTPUT_HARDWARE</code></em></p><p>Set if the clients playback device is not available. Possible values are defined by the enum <span class="structname">HardwareOutputStatus</span>. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_INPUT_DEACTIVATED</code></em></p><p>Set when the capture device has been deactivated as used in Push-To-Talk. Possible values are defined by the enum <span class="structname">InputDeactivationStatus</span>. Only used for the own clients and not available for other clients as it doesn't get propagated to the server.</p></li><li><p><em class="structfield"><code>CLIENT_IDLE_TIME</code></em></p><p>Time the client has been idle. Needs to be requested with <code class="function">ts3client_requestClientVariables</code>.</p></li><li><p><em class="structfield"><code>CLIENT_DEFAULT_CHANNEL</code></em></p><p><em class="structfield"><code>CLIENT_DEFAULT_CHANNEL_PASSWORD</code></em></p><p>Default channel name and password used in the last <code class="function">ts3client_startConnection</code> call. Only available for own client.</p></li><li><p><em class="structfield"><code>CLIENT_META_DATA</code></em></p><p>Not used by TeamSpeak 3, offers free storage for SDK users. Always available for visible clients.</p></li><li><p><em class="structfield"><code>CLIENT_IS_MUTED</code></em></p><p>Indicates a client has been locally muted with <code class="function">ts3client_requestMuteClients</code>. Client-side only.</p></li><li><p><em class="structfield"><code>CLIENT_IS_RECORDING</code></em></p><p>Indicates a client is currently recording all voice data in his channel.</p></li><li><p><em class="structfield"><code>CLIENT_VOLUME_MODIFICATOR</code></em></p><p>The client volume modifier set by <code class="function">ts3client_setClientVolumeModifier</code>.</p></li><li><p><em class="structfield"><code>CLIENT_SECURITY_HASH</code></em></p><p>Contains client security hash (optional feature). This hash is used to check if this client is allowed to enter specified channels with a matching <em class="structfield"><code>CHANNEL_SECURITY_SALT</code></em>. Motivation is to enforce clients joining a server with the specific identity, nickname and metadata.</p><p>Please see the chapter &#8220;<span class="quote">Security salts and hashes</span>&#8221; in the Server SDK documentation for details.</p></li><li><p><em class="structfield"><code>CLIENT_ENCRYPTION_CIPHERS</code></em></p><p>Comma-separated list of ciphers offered to the server to pick one from.</p><p>Possible values are:
</p><pre class="programlisting">
"AES-128"
"AES-256"
</pre><p>
</p><p>Defaults to "AES-256,AES-128".</p></li></ul></div><div class="literallayout"><p><br>
</p></div><p>Generally all types of information can be retrieved as both string or integer. However, in most cases the expected data type is obvious, like querying <em class="structfield"><code>CLIENT_NICKNAME</code></em> will clearly require to store the result as string.</p><p>Example 1: Query client nickname</p><pre class="programlisting">char* nickname;
if(ts3client_getClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, &amp;nickname) == ERROR_ok) {
printf("My nickname is: %s\n", s);
ts3client_freeMemory(s);
}</pre><p>Example 2: Check if own client is currently talking (to be exact: sending voice data)</p><pre class="programlisting">int talking;
if(ts3client_getClientSelfVariableAsInt(scHandlerID, CLIENT_FLAG_TALKING, &amp;talking) == ERROR_ok) {
switch(talking) {
case STATUS_TALKING:
// I am currently talking
break;
case STATUS_NOT_TALKING:
// I am currently not talking
break;
case STATUS_TALKING_WHILE_DISABLED:
// I am talking while microphone is disabled
break;
default:
printf("Invalid value for CLIENT_FLAG_TALKING\n");
}
}</pre><div class="literallayout"><p><br>
</p></div><p>Information related to the own client can be modified with
<a name="setclientselfvarasint"></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_setClientSelfVariableAsInt</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">value</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>ClientProperties <var class="pdparam">flag</var></code>;<br><code>int <var class="pdparam">value</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
<a class="indexterm" name="idm44835433923280"></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_setClientSelfVariableAsString</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">value</var><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code>uint64 <var class="pdparam">serverConnectionHandlerID</var></code>;<br><code>ClientProperties <var class="pdparam">flag</var></code>;<br><code>const char* <var class="pdparam">value</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
<a class="indexterm" name="idm44835433918816"></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 information for the own client is changed.</p></li><li><p><em class="parameter"><code>flag</code></em></p><p>Client propery to query, see above.</p></li><li><p><em class="parameter"><code>value</code></em></p><p>Value the client property should be changed to.</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="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>After modifying one or more client variables, you <span class="emphasis"><em>must</em></span> flush the changes. Flushing ensures the changes are sent to the TeamSpeak 3 server.</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_flushClientSelfUpdates</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">returnCode</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">returnCode</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835433906880"></a></td></tr></table></div><p>The idea behind flushing is, one can modify multiple values by calling <code class="function">ts3client_setClientVariableAsString</code> and <code class="function">ts3client_setClientVariableAsInt</code> and then apply all changes in one step.</p><p>For example, to change the own nickname:</p><pre class="programlisting">/* Modify data */
if(ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_NICKNAME, "Joe") != ERROR_ok) {
printf("Error setting client variable\n");
return;
}
/* Flush changes */
if(ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
printf("Error flushing client updates");
}</pre><p>Example for doing two changes:</p><pre class="programlisting">/* Modify data 1 */
if(ts3client_setClientSelfVariableAsInt(scHandlerID, CLIENT_AWAY, AWAY_ZZZ) != ERROR_ok) {
printf("Error setting away mode\n");
return;
}
/* Modify data 2 */
if(ts3client_setClientSelfVariableAsString(scHandlerID, CLIENT_AWAY_MESSAGE, "Lunch") != ERROR_ok) {
printf("Error setting away message\n");
return;
}
/* Flush changes */
if(ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
printf("Error flushing client updates");
}</pre><p>Example to mute and unmute the microphone:</p><pre class="programlisting">unsigned int error;
bool shouldTalk;
shouldTalk = isPushToTalkButtonPressed(); // Your key detection implementation
if((error = ts3client_setClientSelfVariableAsInt(scHandlerID, CLIENT_INPUT_DEACTIVATED,
shouldTalk ? INPUT_ACTIVE : INPUT_DEACTIVATED)) != ERROR_ok) {
char* errorMsg;
if(ts3client_getErrorMessage(error, &amp;errorMsg) != ERROR_ok) {
printf("Error toggling push-to-talk: %s\n", errorMsg);
ts3client_freeMemory(errorMsg);
}
return;
}
if(ts3client_flushClientSelfUpdates(scHandlerID, NULL) != ERROR_ok) {
char* errorMsg;
if(ts3client_getErrorMessage(error, &amp;errorMsg) != ERROR_ok) {
printf("Error flushing after toggling push-to-talk: %s\n", errorMsg);
ts3client_freeMemory(errorMsg);
}
}</pre><p>See the <a class="link" href="ar01s30.html" title="FAQ">FAQ</a> section for further details on implementing Push-To-Talk with <code class="function">ts3client_setClientSelfVariableAsInt</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="otherclientinfo"></a>Information related to other clients</h4></div></div></div><p>Information related to other clients can be retrieved in a similar way. Unlike own clients however, information cannot be modified.</p><p>To query client related information, use one of the following functions. The parameter <em class="parameter"><code>flag</code></em> is defined by the enum <span class="structname">ClientProperties</span><a class="indexterm" name="idm44835433894944"></a> as shown <a class="link" href="ar01s22.html#clientproperties">above</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_getClientVariableAsInt</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</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>anyID <var class="pdparam">clientID</var></code>;<br><code>ClientProperties <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="idm44835433888688"></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_getClientVariableAsUInt64</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</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>anyID <var class="pdparam">clientID</var></code>;<br><code>ClientProperties <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="idm44835433883136"></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_getClientVariableAsString</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</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>anyID <var class="pdparam">clientID</var></code>;<br><code>ClientProperties <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="idm44835433877584"></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 information for the specified client is requested.</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>Client propery to query, see above.</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></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><div class="literallayout"><p><br>
</p></div><p>As the Client Lib cannot have all information for all users available all the time, the latest data for a given client can be requested from the 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_requestClientVariables</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">returnCode</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">clientID</var></code>;<br><code>const char* <var class="pdparam">returnCode</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
<a class="indexterm" name="idm44835433862448"></a></p><p>The function requires one second delay before calling it again on the same client ID to avoid flooding the server.</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 client variables are requested.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client whose variables are requested.</p></li><li><p><em class="parameter"><code>returnCode</code></em></p><p>See <a class="link" href="ar01s04.html#callingReturnCode" title="Return code">return code documentation</a>. Pass NULL if you do not need this feature.</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 requesting the information, the following event is called. This event is also called everytime a client variable has been changed:
</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">onUpdateClientEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">invokerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">invokerName</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">invokerUniqueIdentifier</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">clientID</var></code>;<br><code>anyID <var class="pdparam">invokerID</var></code>;<br><code>const char* <var class="pdparam">invokerName</var></code>;<br><code>const char* <var class="pdparam">invokerUniqueIdentifier</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
<a class="indexterm" name="idm44835433847584"></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 client variables are now available or have changed.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client whose variables are now available or have changed.</p></li><li><p><em class="parameter"><code>invokerID</code></em></p><p>ID of the client who edited this clients variables.</p></li><li><p><em class="parameter"><code>invokerName</code></em></p><p>Nickname of the client who edited this clients variables.</p></li><li><p><em class="parameter"><code>invokerUniqueIdentifier</code></em></p><p>Unique ID of the client who edited this clients variables.</p></li></ul></div><p>The event does not carry the information per se, but now the Client Lib guarantees to have the clients information available, which can be subsequently queried with <code class="function">ts3client_getClientVariableAsInt</code> and <code class="function">ts3client_getClientVariableAsString</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="whisper"></a>Whisper lists</h4></div></div></div><p>A client with a whisper list set can talk to the specified clients and channels bypassing the standard rule that voice is only transmitted to the current channel. Whisper lists can be defined for individual clients. A whisper list consists of an array of client IDs and/or an array of channel IDs.
</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_requestClientSetWhisperList</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">targetChannelIDArray</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">targetClientIDArray</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">returnCode</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">clientID</var></code>;<br><code>const uint64* <var class="pdparam">targetChannelIDArray</var></code>;<br><code>const anyID* <var class="pdparam">targetClientIDArray</var></code>;<br><code>const char* <var class="pdparam">returnCode</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
<a class="indexterm" name="idm44835433830016"></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 clients whisper list is modified.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the client whose whisper list is modified. If set to 0, the own client is modified (same as setting to own client ID).</p></li><li><p><em class="parameter"><code>targetChannelIDArray</code></em></p><p>Array of channel IDs, terminated with 0. These channels will be added to the whisper list.</p><p>To clear the list, pass NULL or an empty array.</p></li><li><p><em class="parameter"><code>targetClientIDArray</code></em></p><p>Array of client IDs, terminated with 0. These clients will be added to the whisper list.</p><p>To clear the list, pass NULL or an empty array.</p></li><li><p><em class="parameter"><code>returnCode</code></em></p><p>See <a class="link" href="ar01s04.html#callingReturnCode" title="Return code">return code documentation</a>. Pass NULL if you do not need this feature.</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><p>To disable the whisperlist for the given client, pass NULL to both <em class="parameter"><code>targetChannelIDArray</code></em> and <em class="parameter"><code>targetClientIDArray</code></em>. Careful: If you pass two empty arrays, whispering is <span class="emphasis"><em>not</em></span> disabled but instead one would still be whispering to nobody (empty lists).</p><p>To control which client is allowed to whisper to own client, the Client Lib implements an internal whisper whitelist mechanism. When a client recieves a whisper while the whispering client has not yet been added to the whisper allow list, the receiving client gets the following event. Note that whisper voice data is not received until the sending client is added to the receivers whisper allow list.</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">onIgnoredWhisperEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clientID</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">clientID</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835433810992"></a><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 event occured.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>ID of the whispering client.</p></li></ul></div><p>The receiving client can decide to allow whispering from the sender and add the sending client to the whisper allow list by calling <code class="function">ts3client_allowWhispersFrom</code>. If the sender is not added by the receiving client, this event persists being called but no voice data is transmitted to the receiving client.</p><p>To add a client to the whisper allow list:</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_allowWhispersFrom</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clID</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">clID</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835433801984"></a><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 client should be added to the whisper allow list.</p></li><li><p><em class="parameter"><code>clID</code></em></p><p>ID of the client to be added to the whisper allow list.</p></li></ul></div><p>To remove a client from the whisper allow list:</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_removeFromAllowedWhispersFrom</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">clID</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">clID</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835433794032"></a><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 client should be removed from the whisper allow list.</p></li><li><p><em class="parameter"><code>clID</code></em></p><p>ID of the client to be removed from the whisper allow list.</p></li></ul></div><p>It won't have bad sideeffects if the same client ID is added to the whisper allow list multiple times.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s21.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="ar01s22s02.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Query available servers, channels and clients </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"> Channel information</td></tr></table></div></body></html>
Reference in New Issue View Git Blame Copy Permalink