aboutsummaryrefslogtreecommitdiffstats
path: root/doc/protocol.xml
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2011-01-29 09:26:22 +0100
committerMax Kellermann <max@duempel.org>2011-01-29 10:43:54 +0100
commitf8b09c194fe20192c4ac45697e9d0f00e8a96c2c (patch)
treed45c30ce117a7e01431078305ffe2e96d016dc5c /doc/protocol.xml
parent0e69ad32c16eb6449a8952f894c6f239f2e2c52f (diff)
downloadmpd-f8b09c194fe20192c4ac45697e9d0f00e8a96c2c.tar.gz
mpd-f8b09c194fe20192c4ac45697e9d0f00e8a96c2c.tar.xz
mpd-f8b09c194fe20192c4ac45697e9d0f00e8a96c2c.zip
protocol: support client-to-client communication
Diffstat (limited to 'doc/protocol.xml')
-rw-r--r--doc/protocol.xml113
1 files changed, 113 insertions, 0 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml
index a02a94e32..cf4de27c1 100644
--- a/doc/protocol.xml
+++ b/doc/protocol.xml
@@ -204,6 +204,19 @@
has been modified.
</para>
</listitem>
+ <listitem>
+ <para>
+ <returnvalue>subscription</returnvalue>: a client
+ has subscribed or unsubscribed to a channel
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>message</returnvalue>: a message was
+ received on a channel this client is subscribed to;
+ this event is only emitted when the queue is empty
+ </para>
+ </listitem>
</itemizedlist>
<para>
While a client is waiting for <command>idle</command>
@@ -1676,5 +1689,105 @@ suffix: mpc</programlisting>
</varlistentry>
</variablelist>
</section>
+
+ <section>
+ <title>Client to client</title>
+
+ <para>
+ Clients can communicate with each others over "channels". A
+ channel is created by a client subscribing to it. More than
+ one client can be subscribed to a channel at a time; all of
+ them will receive the messages which get sent to it.
+ </para>
+
+ <para>
+ Each time a client subscribes or unsubscribes, the global idle
+ event <varname>subscription</varname> is generated. In
+ conjunction with the <command>channels</command> command, this
+ may be used to auto-detect clients providing additional
+ services.
+ </para>
+
+ <para>
+ A new messages is indicated by the <varname>message</varname>
+ idle event.
+ </para>
+
+ <variablelist>
+ <varlistentry id="command_subscribe">
+ <term>
+ <cmdsynopsis>
+ <command>subscribe</command>
+ <arg choice="req"><replaceable>NAME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Subscribe to a channel. The channel is created if it
+ does not exist already. The name may consist of
+ alphanumeric ASCII characters plus underscore, dash, dot
+ and colon.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="command_unsubscribe">
+ <term>
+ <cmdsynopsis>
+ <command>unsubscribe</command>
+ <arg choice="req"><replaceable>NAME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Unsubscribe from a channel.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="command_channels">
+ <term>
+ <cmdsynopsis>
+ <command>channels</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Obtain a list of all channels. The response is a list
+ of "channel:" lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="command_readmessages">
+ <term>
+ <cmdsynopsis>
+ <command>readmessages</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Reads messages for this client. The response is a list
+ of "channel:" and "message:" lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="command_sendmessage">
+ <term>
+ <cmdsynopsis>
+ <command>sendmessage</command>
+ <arg choice="req"><replaceable>CHANNEL</replaceable></arg>
+ <arg choice="req"><replaceable>TEXT</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Send a message to the specified channel.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
</chapter>
</book>