X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/5abe307a2878e3e523cfd76fa3343cf904c9297f..65bb0fff13f2099c2746d6b8c9ad2421e9419d07:/doc/disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index 07fada9..bf293e9 100644
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -26,10 +26,12 @@ in this man page.
 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.
@@ -90,9 +92,9 @@ Gets the length of the track in seconds.  On success the second field of the
 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
@@ -109,6 +111,10 @@ the queue.  If \fITARGET\fR is listed in the ID list then the tracks are moved
 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)
@@ -188,6 +194,10 @@ Resolve a track name, i.e. if this is an alias then return the real track name.
 .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
@@ -228,14 +238,9 @@ Unset a preference.
 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.
@@ -288,20 +293,20 @@ Text part is just commentary; a dot-stuffed body follows.
 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
@@ -401,6 +406,9 @@ Removed \fIID\fR from the recently played list.
 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
@@ -449,6 +457,63 @@ The volume changed.
 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),