The protocol is liable to change without notice. You are recommended to check
the implementation before believing this document.
.SH "GENERAL SYNTAX"
-Everything is encoded using UTF-8.
+Everything is encoded using UTF-8. See
+.B "CHARACTER ENCODING"
+below for more detail on character encoding issues.
.PP
-Commands and responses consist of a line followed (depending on the
-command or response) by a message.
+Commands and responses consist of a line perhaps followed (depending on the
+command or response) by a body.
.PP
The line syntax is the same as described in \fBdisorder_config\fR(5) except
that comments are prohibited.
response line will have the value.
.TP
.B log
-Sends event log messages in a response body. The command will only terminate (and
-close the response body with a final dot) when a further command is readable on
-the control connection.
+Sends event log messages in a response body. The command will never terminate.
+Any further data sent to the server will be discarded (explicitly; i.e. it will
+not accumulate in a buffer somewhere).
.IP
See \fBEVENT LOG\fR below for more details.
.TP
to just after the first non-listed track before it, or to the head if there is
no such track.
.TP
+.B new \fR[\fIMAX\fR]
+Sends the most recently added \fIMAX\fR tracks in a response body. If the
+argument is ommitted, all recently added tracks are listed.
+.TP
.B nop
Do nothing. Used by
.BR disobedience (1)
.B resume
Resume the current track after a \fBpause\fR command.
.TP
+.B rtp-address
+Reports the RTP broadcast (or multicast) address, in the form \fIADDRESS
+PORT\fR.
+.TP
.B scratch \fR[\fIID\fR]
Remove the track identified by \fIID\fR, or the currently playing track if no
\fIID\fR is specified. If \fBrestrict scratch\fR is enabled in the server's
Unset a global preference.
.TP
.B user \fIUSER\fR \fIRESPONSE\fR
-Authenticate as \fIUSER\fR.
-.IP
-When a connection is made the server sends a \fB221\fR response before any
-command is received. As its first field this contains a challenge string
-encoded in hex.
-.IP
-The \fIRESPONSE\fR consists of the SHA-1 hash of the user's password
-concatenated with the challenge, encoded in hex.
+Authenticate as \fIUSER\fR. See
+.B AUTHENTICATION
+below.
.TP
.B version
Send back a response with the server version as the second field.
Text part is just commentary; an indefinite dot-stuffed body follows. (Used
for \fBlog\fR.)
.TP
-.B 4
-Text part is just commentary; an indefinite dot-stuffed body follows. (Used
-for \fBlog\fR.)
-.TP
.B 9
The text part is just commentary (but would normally be a response for this
command) e.g. \fBplaying\fR.
.SH AUTHENTICATION
-The server starts by issuing a challenge line, with response code 231. This
-contains a random challenge encoded in hex.
+When a connection is made the server sends a \fB231\fR response before any
+command is received. This contains an algorithm name and a challenge encoded
+in hex.
.PP
-The client should send back a \fBuser\fR command with username and a
-hex-encoded response. The response is the SHA-1 hash of the user's password
-and the challenge.
+Currently the algorithm name is omitted if it is \fBsha1\fR (but this will
+probably change in a future version). The other options are \fBsha256\fR,
+\fBsha384\fR and \fBsha512\fR. \fBSHA1\fR etc work as synonyms.
+.PP
+The \fBuser\fR response consists of the selected hash of the user's password
+concatenated with the challenge, encoded in hex.
.SH "TRACK INFORMATION"
Track information is encoded in a line (i.e. using the usual line syntax) as
pairs of fields. The first is a name, the second a value. The names have the
Queue entry \fIID\fR was removed. This is used both for explicit removal (when
\fIUSER\fR is present) and when playing a track (when it is absent).
.TP
+.B rescanned
+A rescan completed.
+.TP
.B scratched \fITRACK\fR \fIUSER\fR
\fITRACK\fR was scratched by \fIUSER\fR.
.TP
is as defined in
.B "TRACK INFORMATION"
above.
+.SH "CHARACTER ENCODING"
+All data sent by both server and client is encoded using UTF-8. Moreover it
+must be valid UTF-8, i.e. non-minimal sequences are not permitted, nor are
+surrogates, nor are code points outside the Unicode code space.
+.PP
+There are no particular normalization requirements on either side of the
+protocol. The server currently converts internally to NFC, the client must
+normalize the responses returned if it needs some normalized form for further
+processing.
+.PP
+The various characters which divide up lines may not be followed by combining
+characters. For instance all of the following are prohibited:
+.TP
+.B o
+LINE FEED followed by a combining character. For example the sequence
+LINE FEED, COMBINING GRAVE ACCENT is never permitted.
+.TP
+.B o
+APOSTROPHE or QUOTATION MARK followed by a combining character when used to
+delimit fields. For instance a line starting APOSTROPHE, COMBINING CEDILLA
+is prohibited.
+.IP
+Note that such sequences are not prohibited when the quote character cannot be
+interpreted as a field delimiter. For instance APOSTROPHE, REVERSE SOLIDUS,
+APOSTROPHE, COMBINING CEDILLA, APOSTROPHE would be permitted.
+.TP
+.B o
+REVERSE SOLIDUS (BACKSLASH) followed by a combining character in a quoted
+string when it is the first character of an escape sequence. For instance a
+line starting APOSTROPHE, REVERSE SOLIDUS, COMBINING TILDE is prohibited.
+.IP
+As above such sequences are not prohibited when the character is not being used
+to start an escape sequence. For instance APOSTROPHE, REVERSE SOLIDUS,
+REVERSE SOLIDS, COMBINING TILDER, APOSTROPHE is permitted.
+.TP
+.B o
+Any of the field-splitting whitespace characters followed by a combining
+character when not part of a quoted field. For instance a line starting COLON,
+SPACE, COMBINING CANDRABINDU is prohibited.
+.IP
+As above non-delimiter uses are fine.
+.TP
+.B o
+The FULL STOP characters used to quote or delimit a body.
+.PP
+Furthermore none of these characters are permitted to appear in the context of
+a canonical decomposition (i.e. they must still be present when converted to
+NFC). In practice however this is not an issue in Unicode 5.0.
+.PP
+These rules are consistent with the observation that the split() function is
+essentially a naive ASCII parser. The implication is not that these sequences
+never actually appear in the protocol, merely that the server is not required
+to honor them in any useful way nor be consistent between versions: in current
+versions the result will be lines and fields that start with combining
+characters and are not necessarily split where you expect, but future versions
+may remove them, reject them or ignore some or all of the delimiters that have
+following combining characters, and no notice will be given of any change.
.SH "SEE ALSO"
\fBdisorder\fR(1),
\fBtime\fR(2),
~mdw / disorder / blobdiff