From 3680a6bbbb6c2ae26d5c9bf361bc2feea362b553 Mon Sep 17 00:00:00 2001
From: Jonathan Ballet <jon@multani.info>
Date: Sun, 3 Jul 2011 15:05:04 +0200
Subject: doc/protocol: add some missing specifications
---
doc/protocol.xml | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 127 insertions(+), 7 deletions(-)
(limited to 'doc')
diff --git a/doc/protocol.xml b/doc/protocol.xml
index 3eb5aa932..0b4f0d175 100644
--- a/doc/protocol.xml
+++ b/doc/protocol.xml
@@ -8,18 +8,54 @@
<title>General protocol syntax</title>
<section>
- <title>Requests</title>
+ <title>Protocol overview</title>
+
+ <para>
+ The MPD command protocol exchanges line-based text records
+ between client and server over TCP. Once the client is
+ connected to the server, they conduct a conversation until the
+ client closes the connection. The conversation flow is always
+ initiated by the client.
+ </para>
+
+ <para>
+ The client transmits a command sequence, terminated by the
+ newline character <constant>\n</constant>. The server will
+ respond with one or more lines, the last of which will be a
+ completion code.
+ </para>
<para>
- If arguments contain spaces, they should be surrounded by double quotation
- marks.
+ When the client connects to the server, the server will answer
+ with the following line:
+
+ <synopsis>OK MPD version</synopsis>
+
+ where <varname>version</varname> is a version identifier such as
+ 0.12.2. This version identifier is the version of the protocol
+ spoken, not the real version of the daemon. (There is no way to
+ retrieve this real version identifier from the connection.)
</para>
+ </section>
+
+ <section>
+ <title>Requests</title>
<cmdsynopsis>
<command>COMMAND</command>
<arg rep="repeat"><replaceable>ARG</replaceable></arg>
</cmdsynopsis>
+ <para>
+ If arguments contain spaces, they should be surrounded by double
+ quotation marks.
+ </para>
+
+ <para>
+ Argument strings are separated from the command and any other
+ arguments by linear white-space (' ' or '\t').
+ </para>
+
<para>
All data between the client and the server is encoded in
UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are
@@ -38,13 +74,97 @@
<title>Responses</title>
<para>
- A command returns <returnvalue>OK</returnvalue> on completion
- or <returnvalue>ACK some error</returnvalue> on failure.
- These denote the end of command execution.
+ A command returns <returnvalue>OK</returnvalue> on completion or
+ <returnvalue>ACK some error</returnvalue> on failure. These
+ denote the end of command execution.
</para>
+
+ <section>
+ <title>Failure responses</title>
+
+ <para>
+ The nature of the error can be gleaned from the information
+ that follows the <returnvalue>ACK</returnvalue>.
+ <returnvalue>ACK</returnvalue> lines are of the form:
+
+ <synopsis>ACK [error@command_listNum] {current_command} message_text\n</synopsis>
+
+ These responses are generated by a call to
+ <function>commandError</function>. They contain four separate
+ terms. Let's look at each of them:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <returnvalue>error</returnvalue>: numeric value of one
+ of the <constant>ACK_ERROR</constant> constants defined
+ in <filename>ack.h</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>command_listNum</returnvalue>:
+ offset of the command that caused the error in a <link
+ linkend="command_lists">Command List</link>.
+ An error will always cause a command list to terminate
+ at the command that causes the error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>current_command</returnvalue>:
+ name of the command, in a <link
+ linkend="command_lists">Command List</link>,
+ that was executing when the error occurred.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>message_text</returnvalue>:
+ some (hopefully) informative text that describes the
+ nature of the error.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <example>
+ <title>foo</title>
+ <para>
+ An example might help. Consider the following sequence
+ sent from the client to the server.
+
+ <synopsis>
+ command_list_begin
+ volume 86
+ play 10240
+ status
+ command_list_end
+ </synopsis>
+ </para>
+
+ <para>
+ The server responds with:
+
+ <returnvalue>
+ ACK [50@1] {play} song doesn't exist: "10240"
+ </returnvalue>
+ </para>
+
+ <para>
+ This tells us that the play command, which was the
+ second in the list (the first or only command is
+ numbered 0), failed with error 50. The number 50
+ translates to <constant>ACK_ERROR_NO_EXIST</constant>--the
+ song doesn't exist. This is reiterated by the message text
+ which also tells us which song doesn't exist.
+ </para>
+
+ </example>
+ </section>
</section>
- <section>
+ <section id="command_lists">
<title>Command lists</title>
<para>
--
cgit v1.2.3