oysteikt/mpd
0
0
Fork 0
Code Issues Pull Requests Releases Activity

doc/protocol.rst: several clarifications

Browse Source 
Closes https://github.com/MusicPlayerDaemon/MPD/issues/340
This commit is contained in:
Max Kellermann 2019-05-20 17:06:20 +02:00
parent 923e66738c
commit 1b902e00b4
1 changed files with 30 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/protocol.rst
View File

@ -14,6 +14,9 @@ Once the client is connected to the server, they conduct a
conversation until the client closes the connection. The conversation until the client closes the connection. The
conversation flow is always initiated by the client. conversation flow is always initiated by the client.
All data between the client and the server is encoded in
UTF-8.
The client transmits a command sequence, terminated by the The client transmits a command sequence, terminated by the
newline character ``\n``. The server will newline character ``\n``. The server will
respond with one or more lines, the last of which will be a respond with one or more lines, the last of which will be a
@ -42,9 +45,6 @@ quotation marks.
Argument strings are separated from the command and any other Argument strings are separated from the command and any other
arguments by linear white-space (' ' or '\\t'). arguments by linear white-space (' ' or '\\t').
All data between the client and the server is encoded in
UTF-8.
Responses Responses
========= =========
@ -52,6 +52,28 @@ A command returns ``OK`` on completion or
``ACK some error`` on failure. These ``ACK some error`` on failure. These
denote the end of command execution. denote the end of command execution.
Some commands return more data before the response ends with ``OK``.
Each line is usually in the form ``NAME: VALUE``. Example::
foo: bar
OK
.. _binary:
Binary Responses
----------------
Some commands can return binary data. This is initiated by a line
containing ``binary: 1234`` (followed as usual by a newline). After
that, the specified number of bytes of binary data follows (without an
extra newline, because this binary data is not a text line), and
finally the ``OK`` line. Example::
foo: bar
binary: 42
<42 bytes>OK
Failure responses Failure responses
----------------- -----------------
@ -112,9 +134,9 @@ list begins with `command_list_begin` or
`command_list_ok_begin` and ends with `command_list_ok_begin` and ends with
`command_list_end`. `command_list_end`.
It does not execute any commands until the list has ended. It does not execute any commands until the list has ended. The
The return value is whatever the return for a list of commands response is a concatentation of all individual responses.
is. On success for all commands, On success for all commands,
``OK`` is returned. If a command ``OK`` is returned. If a command
fails, no more commands are executed and the appropriate fails, no more commands are executed and the appropriate
``ACK`` error is returned. If ``ACK`` error is returned. If
@ -794,7 +816,7 @@ The music database
Returns the file size and actual number Returns the file size and actual number
of bytes read at the requested offset, followed of bytes read at the requested offset, followed
by the chunk requested as raw bytes, then a by the chunk requested as raw bytes (see :ref:`binary`), then a
newline and the completion code. newline and the completion code.
Example:: Example::
@ -802,8 +824,7 @@ The music database
albumart albumart
size: 1024768 size: 1024768
binary: 8192 binary: 8192
<8192 bytes> <8192 bytes>OK
OK
:command:`count {FILTER} [group {GROUPTYPE}]` :command:`count {FILTER} [group {GROUPTYPE}]`
Count the number of songs and their total playtime in Count the number of songs and their total playtime in