Files
ts-mobile-go/docs/teamspeak-sdk-3.5.2/doc/client/channel-join.html
T
2026-07-20 19:01:03 +08:00

286 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Joining a channel &mdash; TeamSpeak SDK documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=7f41d439"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Channel subscriptions" href="channel-subscribe.html" />
<link rel="prev" title="Deleting a channel" href="channel-delete.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
TeamSpeak SDK
<img src="../_static/logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../errors.html">TeamSpeak Error Codes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../properties.html">Property Enums</a></li>
<li class="toctree-l1"><a class="reference internal" href="../enumerations.html">Structures &amp; Enumerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../client_api.html">TeamSpeak Client Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server_api.html">TeamSpeak Server Functions</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Server</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../server/intro.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/basic.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/list-items.html">List available clients, channels, servers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/vserver-manage.html">Create and stop virtual servers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/advanced-create.html">Advanced virtual server creation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/info.html">Retrieve and store information</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/channels.html">Managing channels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/clients.html">Managing clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/whisper.html">Whisper lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/encryption.html">Custom encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/passwords.html">Custom passwords</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/permissions.html">Permission checks</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/security-salt.html">Security salts and hashes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/disable-commands.html">Disabling protocol commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/filetransfer.html">Filetransfer</a></li>
<li class="toctree-l1"><a class="reference internal" href="../server/faq.html">FAQ</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Client</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="basic.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="connections.html">Managing server connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="logging.html">Logging</a></li>
<li class="toctree-l1"><a class="reference internal" href="audio.html">Client Audio</a></li>
<li class="toctree-l1"><a class="reference internal" href="wave-files.html">Playing wave files</a></li>
<li class="toctree-l1"><a class="reference internal" href="3dsound.html">3D Sound</a></li>
<li class="toctree-l1"><a class="reference internal" href="whisper.html">Whisper lists</a></li>
<li class="toctree-l1"><a class="reference internal" href="voice-encryption.html">Channel voice data encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="info.html">Retrieve and store information</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="channels.html">Channel Management</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="channel-list.html">List channels</a></li>
<li class="toctree-l2"><a class="reference internal" href="info-channel.html">Channel information</a></li>
<li class="toctree-l2"><a class="reference internal" href="channel-create.html">Creating a new channel</a></li>
<li class="toctree-l2"><a class="reference internal" href="channel-move.html">Moving a channel</a></li>
<li class="toctree-l2"><a class="reference internal" href="channel-sort.html">Channel sorting</a></li>
<li class="toctree-l2"><a class="reference internal" href="channel-delete.html">Deleting a channel</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Joining a channel</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="channel-subscribe.html">Channel subscriptions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="client-list.html">List clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="client-kick.html">Kicking clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="local-mute.html">Muting other clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="textmessages.html">Text chat</a></li>
<li class="toctree-l1"><a class="reference internal" href="filetransfer.html">Filetransfer</a></li>
<li class="toctree-l1"><a class="reference internal" href="encryption.html">Custom encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="passwords.html">Custom passwords</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">TeamSpeak SDK</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="channels.html">Channel Management</a></li>
<li class="breadcrumb-item active">Joining a channel</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="joining-a-channel">
<h1>Joining a channel<a class="headerlink" href="#joining-a-channel" title="Link to this heading"></a></h1>
<p>When a client logs on to a TeamSpeak 3 server, it will automatically
join the channel with the <a class="reference internal" href="../properties.html#c.ChannelProperties.CHANNEL_FLAG_DEFAULT" title="ChannelProperties.CHANNEL_FLAG_DEFAULT"><code class="xref c c-enumerator docutils literal notranslate"><span class="pre">CHANNEL_FLAG_DEFAULT</span></code></a> flag,
unless it specified a different channel in the <a class="reference internal" href="connections.html#c.ts3client_startConnection" title="ts3client_startConnection"><code class="xref c c-func docutils literal notranslate"><span class="pre">ts3client_startConnection()</span></code></a> call.</p>
<p>To join a different channel, or move another client to a different channel, call</p>
<dl class="c function">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ts3client_requestClientMove</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">serverConnectionHandlerID</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">anyID</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">clientIDArray</span></span>, <span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">newChannelID</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">password</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">returnCode</span></span><span class="sig-paren">)</span><br /></dt>
<dd><p>Attempt to move one or more clients to a different channel. </p>
<p>The move is requested from the server. See the onServerErrorEvent callback to know whether the move was successful or not.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>serverConnectionHandlerID</strong> the connection handler of which the channel and client are located </p></li>
<li><p><strong>clientIDArray</strong> NULL terminated array of client ids to move </p></li>
<li><p><strong>newChannelID</strong> the target channel id to move the clients to </p></li>
<li><p><strong>password</strong> the password for the channel. Pass an empty string if the channel has no password. </p></li>
<li><p><strong>returnCode</strong> a c string to identify this request in callbacks. Pass an empty string if unused. </p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Error code from the <a class="reference internal" href="../errors.html#public__errors_8h_1a0bcf1e0a5e32989890f6e85064327f7b"><span class="std std-ref">Ts3ErrorType</span></a> enum indicating either success or the failure reason </p>
</dd>
</dl>
</dd></dl>
<p>If successful one of the following callbacks will be called depending whether
you moved your own or a different client</p>
<dl class="c struct">
<dt class="sig sig-object c">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">ClientUIFunctions</span></span></span><br /></dt>
<dd><p>Defines available callbacks that you can receive. </p>
<p>Set the members of this struct to a function to call when the specific event happens. </p>
<div class="breathe-sectiondef docutils container">
<p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-members">Public Members</p>
<dl class="c var">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">onClientMoveEvent</span></span></span><span class="p"><span class="pre">)</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">serverConnectionHandlerID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">anyID</span></span><span class="w"> </span><span class="n"><span class="pre">clientID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">oldChannelID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">newChannelID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">visibility</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">moveMessage</span></span><span class="p"><span class="pre">)</span></span><br /></dt>
<dd><p>called when a client moves to a different channel, disconnects, connects, gets kicked or banned. </p>
<dl class="field-list simple">
<dt class="field-odd">Param serverConnectionHandlerID<span class="colon">:</span></dt>
<dd class="field-odd"><p>specifies on which connection the callback was called </p>
</dd>
<dt class="field-even">Param clientID<span class="colon">:</span></dt>
<dd class="field-even"><p>id of the client changing channels </p>
</dd>
<dt class="field-odd">Param oldChannelID<span class="colon">:</span></dt>
<dd class="field-odd"><p>id of the previous channel of the client. </p>
</dd>
<dt class="field-even">Param newChannelID<span class="colon">:</span></dt>
<dd class="field-even"><p>id of the current channel of the client. Can be 0, if the client disconnected / got kicked / banned. </p>
</dd>
</dl>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">onClientMoveMovedEvent</span></span></span><span class="p"><span class="pre">)</span></span><span class="p"><span class="pre">(</span></span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">serverConnectionHandlerID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">anyID</span></span><span class="w"> </span><span class="n"><span class="pre">clientID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">oldChannelID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">uint64</span></span><span class="w"> </span><span class="n"><span class="pre">newChannelID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">visibility</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="n"><span class="pre">anyID</span></span><span class="w"> </span><span class="n"><span class="pre">moverID</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">moverName</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">moverUniqueIdentifier</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">moveMessage</span></span><span class="p"><span class="pre">)</span></span><br /></dt>
<dd><p>called when a client was moved by the server or another client </p>
<dl class="field-list simple">
<dt class="field-odd">Param serverConnectionHandlerID<span class="colon">:</span></dt>
<dd class="field-odd"><p>specifies on which connection the callback was called </p>
</dd>
<dt class="field-even">Param clientID<span class="colon">:</span></dt>
<dd class="field-even"><p>the client that was moved </p>
</dd>
<dt class="field-odd">Param oldChannelID<span class="colon">:</span></dt>
<dd class="field-odd"><p>id of the previous channel the client used to be in </p>
</dd>
<dt class="field-even">Param newChannelID<span class="colon">:</span></dt>
<dd class="field-even"><p>id of the current channel the client was moved to </p>
</dd>
<dt class="field-odd">Param visibility<span class="colon">:</span></dt>
<dd class="field-odd"><p>whether we can see the client. One of the values from the Visibility enum. </p>
</dd>
<dt class="field-even">Param moverID<span class="colon">:</span></dt>
<dd class="field-even"><p>id of the client that moved the client </p>
</dd>
<dt class="field-odd">Param moverName<span class="colon">:</span></dt>
<dd class="field-odd"><p>utf8 encoded c string containing the display name of the client that caused the move </p>
</dd>
<dt class="field-even">Param moverUniqueIdentifier<span class="colon">:</span></dt>
<dd class="field-even"><p>utf8 encoded c string containing the identifier of the client that caused the move </p>
</dd>
<dt class="field-odd">Param moveMessage<span class="colon">:</span></dt>
<dd class="field-odd"><p>utf8 encoded c string containing the reason message </p>
</dd>
</dl>
</dd></dl>
</div>
</dd></dl>
<section id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
<p>Requesting to move the own client into channel ID 12 (not password-protected):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ts3client_requestClientMove</span><span class="p">(</span><span class="n">scHandlerID</span><span class="p">,</span><span class="w"> </span><span class="n">ts3client_getClientID</span><span class="p">(</span><span class="n">scHandlerID</span><span class="p">),</span><span class="w"> </span><span class="mi">12</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">);</span>
</pre></div>
</div>
<p>Now wait for the callback:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span><span class="w"> </span><span class="nf">my_onClientMoveEvent</span><span class="p">(</span><span class="n">uint64</span><span class="w"> </span><span class="n">scHandlerID</span><span class="p">,</span><span class="w"> </span><span class="n">anyID</span><span class="w"> </span><span class="n">clientID</span><span class="p">,</span>
<span class="w"> </span><span class="n">uint64</span><span class="w"> </span><span class="n">oldChannelID</span><span class="p">,</span><span class="w"> </span><span class="n">uint64</span><span class="w"> </span><span class="n">newChannelID</span><span class="p">,</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">visibility</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="w"> </span><span class="n">moveMessage</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="c1">// scHandlerID -&gt; Server connection handler ID, same as above when requesting</span>
<span class="w"> </span><span class="c1">// clientID -&gt; Own client ID, same as above when requesting</span>
<span class="w"> </span><span class="c1">// oldChannelID -&gt; ID of the channel the client has left</span>
<span class="w"> </span><span class="c1">// newChannelID -&gt; 12, as requested above</span>
<span class="w"> </span><span class="c1">// visibility -&gt; One of ENTER_VISIBILITY, RETAIN_VISIBILITY, LEAVE_VISIBILITY</span>
<span class="w"> </span><span class="c1">// moveMessage -&gt; Optional message set by disconnecting clients</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If <code class="docutils literal notranslate"><span class="pre">oldChannelID</span></code> is 0, the client has just connected to the server.
If <code class="docutils literal notranslate"><span class="pre">newChannelID</span></code> is 0, the client disconnected.</p>
<p>Both values cannot be 0 at the same time.</p>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="channel-delete.html" class="btn btn-neutral float-left" title="Deleting a channel" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="channel-subscribe.html" class="btn btn-neutral float-right" title="Channel subscriptions" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2020, TeamSpeak Systems GmbH.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>