29 lines
12 KiB
HTML
29 lines
12 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Channel subscriptions</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="ar01s23.html" title="Interacting with the server"><link rel="prev" href="ar01s23s06.html" title="Kicking clients"><link rel="next" href="ar01s24.html" title="Muting clients locally"></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">Channel subscriptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s23s06.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">Interacting with the server</th><td width="20%" align="right"> <a accesskey="n" href="ar01s24.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="subscribe"></a>Channel subscriptions</h3></div></div></div><p>Normally a user only sees other clients who are in the same channel. Clients joining or leaving other channels or changing status are not displayed. To offer a way to get notifications about clients in other channels, a user can subscribe to other channels. It would also be possible to always subscribe to all channels to get notifications about all clients on the server.</p><p>Subscriptions are meant to have a flexible way to balance bandwidth usage. On a crowded server limiting the number of subscribed channels is a way to reduce network traffic. Also subscriptions allow to usage “<span class="quote">private</span>” channels, whose members cannot be seen by other users.</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>A client is automatically subscribed to the current channel.</p></td></tr></table></div><p>To subscribe to a list of channels (zero-terminated array of channel IDs) 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_requestChannelSubscribe</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelIDArray</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 uint64* <var class="pdparam">channelIDArray</var></code>;<br><code>const char* <var class="pdparam">returnCode</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433237488"></a></p><p>To unsubscribe from a list of channels (zero-terminated array of channel IDs) 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_requestChannelUnsubscribe</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelIDArray</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 uint64* <var class="pdparam">channelIDArray</var></code>;<br><code>const char* <var class="pdparam">returnCode</var></code>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433232672"></a></p><p>To subscribe to all channels on the server 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_requestChannelSubscribeAll</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><p>
|
||
<a class="indexterm" name="idm44835433228592"></a></p><p>To unsubscribe from all channels on the server 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_requestChannelUnsubscribeAll</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><p>
|
||
<a class="indexterm" name="idm44835433224512"></a></p><p>To check if a channel is currently subscribed, check the channel property <em class="structfield"><code>CHANNEL_FLAG_ARE_SUBSCRIBED</code></em> with <a class="link" href="ar01s22s02.html" title="Channel information"><code class="function">ts3client_getChannelVariableAsInt</code></a>:</p><pre class="programlisting">int isSubscribed;
|
||
|
||
if(ts3client_getChannelVariableAsInt(scHandlerID, channelID, CHANNEL_FLAG_ARE_SUBSCRIBED, &isSubscribed)
|
||
!= ERROR_ok) {
|
||
/* Handle error */
|
||
}</pre><p>The following event will be sent for each successfully subscribed channel:
|
||
</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">onChannelSubscribeEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelID</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>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433218016"></a></p><p>Provided for convinience, to mark the end of mulitple calls to <code class="function">onChannelSubscribeEvent</code> when subscribing to several channels, this event is called:
|
||
</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">onChannelSubscribeFinishedEvent</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="idm44835433214144"></a></p><p>The following event will be sent for each successfully unsubscribed channel:
|
||
</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">onChannelUnsubscribeEvent</b>(</code></td><td><var class="pdparam">serverConnectionHandlerID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">channelID</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>;</div><div class="funcprototype-spacer"> </div></div><p>
|
||
<a class="indexterm" name="idm44835433210032"></a></p><p>Similar like subscribing, this event is a convinience callback to mark the end of multiple calls to <code class="function">onChannelUnsubscribeEvent</code>:
|
||
</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">onChannelUnsubscribeFinishedEvent</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="idm44835433206176"></a></p><p>Once a channel has been subscribed or unsubscribed, the event <code class="function">onClientMoveSubscriptionEvent</code> is sent for each client in the subscribed channel. The event is not to be confused with <code class="function">onClientMoveEvent</code>, which is called for clients actively switching channels.</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">onClientMoveSubscriptionEvent</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">oldChannelID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">newChannelID</var>, </td><td> </td></tr><tr><td> </td><td><var class="pdparam">visibility</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>uint64 <var class="pdparam">oldChannelID</var></code>;<br><code>uint64 <var class="pdparam">newChannelID</var></code>;<br><code>int <var class="pdparam">visibility</var></code>;</div><div class="funcprototype-spacer"> </div></div><a class="indexterm" name="idm44835433198800"></a><div class="itemizedlist"><ul type="disc"><li><p><em class="parameter"><code>serverConnectionHandlerID</code></em></p><p>The server connection handler ID for the server where the action occured.</p></li><li><p><em class="parameter"><code>clientID</code></em></p><p>The client ID.</p></li><li><p><em class="parameter"><code>oldChannelID</code></em></p><p>ID of the subscribed channel where the client left visibility.</p></li><li><p><em class="parameter"><code>newChannelID</code></em></p><p>ID of the subscribed channel where the client entered visibility.</p></li><li><p><em class="parameter"><code>visibility</code></em></p><p>Defined in the enum <span class="structname">Visibility</span><a class="indexterm" name="idm44835433189408"></a>
|
||
</p><pre class="programlisting">enum Visibility {
|
||
ENTER_VISIBILITY = 0,
|
||
RETAIN_VISIBILITY,
|
||
LEAVE_VISIBILITY
|
||
};</pre><p>
|
||
</p><div class="itemizedlist"><ul type="circle"><li><p><em class="structfield"><code>ENTER_VISIBILITY</code></em></p><p>Client entered visibility.</p></li><li><p><em class="structfield"><code>LEAVE_VISIBILITY</code></em></p><p>Client left visibility.</p></li><li><p><em class="structfield"><code>RETAIN_VISIBILITY</code></em></p><p>Does not occur with onClientMoveSubscriptionEvent.</p></li></ul></div></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s23s06.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ar01s23.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s24.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Kicking 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"> Muting clients locally</td></tr></table></div></body></html>
|