diff options
| -rw-r--r-- | doc/protocol.xml | 134 |
1 files changed, 127 insertions, 7 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml index 3eb5aa932..0b4f0d175 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -8,12 +8,38 @@ <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> @@ -21,6 +47,16 @@ </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 the same as a standard ansi encoding. Also, no ansi character @@ -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> |