align with disorder.unicode a bit

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index d3ad537aee8d47f81b77423cd49622cb1275298e..d20edcf571896866e105b0942f40ae12150a9f38 100644 (file)
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -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
 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
 .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
 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 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 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
 .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
 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.
 .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
 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
 .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
 .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
 .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
 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
 .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
 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
 .B disable_play
 Playing was disabled.
 .TP


@@ -420,11 +429,23 @@ Playing was enabled.
 .B enable_random
 Random play was enabled.
 .TP
 .B enable_random
 Random play was enabled.
 .TP

+.B failed
+The current track failed.
+.TP

 .B pause
 The current track was paused.
 .TP
 .B pause
 The current track was paused.
 .TP

+.B playing
+A track started playing.
+.TP

 .B resume
 The current track was resumed.
 .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
 .RE
 .TP
 .B volume \fILEFT\fR \fIRIGHT\fR