chiark / gitweb /
align with disorder.unicode a bit
[disorder] / doc / disorder_protocol.5.in
index d3ad537..d20edcf 100644 (file)
@@ -90,9 +90,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 +109,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 +192,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 +236,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 +291,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
+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 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.
+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 +404,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
@@ -408,6 +414,9 @@ Queue entry \fIID\fR was removed.  This is used both for explicit removal (when
 Some state change occurred.  The current set of keywords is:
 .RS
 .TP
+.B completed
+The current track completed successfully.
+.TP
 .B disable_play
 Playing was disabled.
 .TP
@@ -420,11 +429,23 @@ Playing was enabled.
 .B enable_random
 Random play was enabled.
 .TP
+.B failed
+The current track failed.
+.TP
 .B pause
 The current track was paused.
 .TP
+.B playing
+A track started playing.
+.TP
 .B resume
 The current track was resumed.
+.TP
+.B scratched
+The current track was scratched.
+.PP
+To simplify client implementation, \fBstate\fR commands reflecting the current
+state are sent at the start of the log.
 .RE
 .TP
 .B volume \fILEFT\fR \fIRIGHT\fR