X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/763d5e6ad88ef3ba1cd1d7742d060e4f1e54c6b8..d42e98caaaf4f07c8d1252236f03eb68b8be4619:/doc/disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index f3af468..ba37e67 100644
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -1,20 +1,18 @@
 .\"
-.\" Copyright (C) 2004, 2005, 2006 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell
 .\"
-.\" This program is free software; you can redistribute it and/or modify
+.\" This program is free software: you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or
 .\" (at your option) any later version.
-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
+.\" 
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\" 
 .\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .\"
 .TH disorder_protocol 5
 .SH NAME
@@ -23,13 +21,16 @@ disorder_protocol \- DisOrder communication protocol
 The DisOrder client and server communicate via the protocol described
 in this man page.
 .PP
-The protocol is liable to change without notice.  You are recommended to check
-the implementation before believing this document.
+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.
+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.
@@ -39,79 +40,143 @@ lines, with any initial full stop doubled up, and are terminated by a line
 consisting of a full stop and a line feed.
 .SH COMMANDS
 Commands always have a command name as the first field of the line; responses
-always have a 3-digit response code as the first field.  See below for more
-details about this field.
+always have a 3-digit response code as the first field.
+See below for more details about this field.
 .PP
 All commands require the connection to have been already authenticated unless
 stated otherwise.
+If not stated otherwise, the \fBread\fR right is sufficient to execute
+the command.
 .PP
 Neither commands nor responses have a body unless stated otherwise.
 .TP
+.B adduser \fIUSERNAME PASSWORD \fR[\fIRIGHTS\fR]
+Create a new user with the given username and password.
+The new user's rights list can be specified; if it is not
+then the \fBdefault_rights\fR setting applies instead.
+Requires the \fBadmin\fR right, and only works on local
+connections.
+.TP
+.B adopt \fIID\fR
+Adopts a randomly picked track, leaving it in a similar state to if it was
+picked by this user.  Requires the \fBplay\fR right.
+.TP
 .B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
-Lists all the files and directories in \fIDIRECTORY\fR in a response body.
+List all the files and directories in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching files and directories are returned.
 .TP
-.B become \fIUSER\fR
-Instructs the server to treat the connection as if \fIUSER\fR had
-authenticated it.  Only trusted users may issue this command.
+.B confirm \fICONFIRMATION
+Confirm user registration.
+\fICONFIRMATION\fR is as returned from \fBregister\fR below.
+This command can be used without logging in.
+.TP
+.B cookie \fICOOKIE
+Log a user back in using a cookie created with \fBmake\-cookie\fR.
+The response contains the username.
+.TP
+.B deluser \fIUSERNAME
+Delete the named user.
+Requires the \fBadmin\fR right, and only works on local connections.
 .TP
 .B dirs \fIDIRECTORY\fR [\fIREGEXP\fR]
-Lists all the directories in \fIDIRECTORY\fR in a response body.
+List all the directories in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching directories are returned.
 .TP
 .B disable \fR[\fBnow\fR]
-Disables further playing.  If the optional \fBnow\fR argument is present then
-the current track is stopped.
+Disable further playing.
+If the optional \fBnow\fR argument is present then the current track
+is stopped.
+Requires the \fBglobal prefs\fR right.
+.TP
+.B edituser \fIUSERNAME PROPERTY VALUE
+Set a user property.
+With the \fBadmin\fR right any username and property may be specified.
+Otherwise the \fBuserinfo\fR right is required and only the
+\fBemail\fR and \fBpassword\fR properties may be set.
+.IP
+User properties are syntax-checked before setting.  For instance \fBemail\fR
+must contain an "@" sign or you will get an error.  (Setting an empty value for
+\fBemail\fR is allowed and removes the property.)
 .TP
 .B enable
-Re-enables further playing, and is the opposite of \fBdisable\fR.
+Re-enable further playing, and is the opposite of \fBdisable\fR.
+Requires the \fBglobal prefs\fR right.
 .TP
 .B enabled
-Reports whether playing is enabled.  The second field of the response line will
-be \fByes\fR or \fBno\fR.
+Report whether playing is enabled.
+The second field of the response line will be \fByes\fR or \fBno\fR.
 .TP
 .B exists \fITRACK\fR
-Reports whether the named track exists.  The second field of the response line
-will be \fByes\fR or \fBno\fR.
+Report whether the named track exists.
+The second field of the response line will be \fByes\fR or \fBno\fR.
 .TP
 .B files \fIDIRECTORY\fR [\fIREGEXP\fR]
-Lists all the files in \fIDIRECTORY\fR in a response body.
+List all the files in \fIDIRECTORY\fR in a response body.
 If \fIREGEXP\fR is present only matching files are returned.
 .TP
 .B get \fITRACK\fR \fIPREF\fR
-Gets a preference value.  On success the second field of the response line will
-have the value.
+Getsa preference value.
+On success the second field of the response line will have the value.
+.IP
+If the track or preference do not exist then the response code is 555.
 .TP
-.B get-global \fIKEY\fR
+.B get\-global \fIKEY\fR
 Get a global preference.
+.IP
+If the preference does not exist then the response code is 555.
 .TP
 .B length \fITRACK\fR
-Gets the length of the track in seconds.  On success the second field of the
-response line will have the value.
+Get 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.
+Send 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
+.B make\-cookie
+Returns an opaque string that can be used by the \fBcookie\fR command to log
+this user back in on another connection (until the cookie expires).
+.TP
 .B move \fITRACK\fR \fIDELTA\fR
-Move a track in the queue.  The track may be identified by ID (preferred) or
-name (which might cause confusion if it's there twice).  \fIDELTA\fR should be
-an negative or positive integer and indicates how many steps towards the head
-of the queue the track should be moved.
+Move a track in the queue.
+The track may be identified by ID (preferred) or name (which might cause
+confusion if it's there twice).
+\fIDELTA\fR should be an negative or positive integer and indicates how
+many steps towards the head of the queue the track should be moved.
+.IP
+Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
+depending on how the track came to be added to the queue.
 .TP
 .B moveafter \fITARGET\fR \fIID\fR ...
-Move all the tracks in the \fIID\fR list after ID \fITARGET\fR.  If
-\fITARGET\fR is the empty string then the listed tracks are put at the head of
-the queue.  If \fITARGET\fR is listed in the ID list then the tracks are moved
+Move all the tracks in the \fIID\fR list after ID \fITARGET\fR.
+If \fITARGET\fR is the empty string then the listed tracks are put
+at the head of 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.
+.IP
+Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
+depending on how the tracks came to be added to the queue.
+.TP
+.B new \fR[\fIMAX\fR]
+Send the most recently added \fIMAX\fR tracks in a response body.
+If the argument is ommitted, the \fBnew_max\fR most recent tracks are
+listed (see \fBdisorder_config\fR(5)).
+.TP
+.B nop
+Do nothing.
+Used by
+.BR disobedience (1)
+as a keepalive measure.
+This command does not require authentication.
 .TP
 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
-Get a track name part.  Returns an empty string if a name part cannot be
-constructed.
+Get a track name part.
+Returns an empty string if a name part cannot be constructed.
 .IP
 .I CONTEXT
 is one of
@@ -128,12 +193,15 @@ or
 .TP
 .B pause
 Pause the current track.
+Requires the \fBpause\fR right.
 .TP
 .B play \fITRACK\fR
 Add a track to the queue.
+The response contains the queue ID of the track.
+Requires the \fBplay\fR right.
 .TP
 .B playing
-Reports what track is playing.
+Report what track is playing.
 .IP
 If the response is \fB252\fR then the rest of the response line consists of
 track information (see below).
@@ -141,59 +209,155 @@ track information (see below).
 If the response is \fB259\fR then nothing is playing.
 .TP
 .B prefs \fBTRACK\fR
-Sends back the preferences for \fITRACK\fR in a response body.
+Send back the preferences for \fITRACK\fR in a response body.
 Each line of the response has the usual line syntax, the first field being the
 name of the pref and the second the value.
 .TP
 .B queue
-Sends back the current queue in a response body, one track to a line, the track
-at the head of the queue (i.e. next to be be played) first.  See below for the
-track information syntax.
+Send back the current queue in a response body, one track to a line, the track
+at the head of the queue (i.e. next to be be played) first.
+See below for the track information syntax.
 .TP
-.B random-disable
+.B random\-disable
 Disable random play (but don't stop the current track).
+Requires the \fBglobal prefs\fR right.
 .TP
-.B random-enable
+.B random\-enable
 Enable random play.
+Requires the \fBglobal prefs\fR right.
 .TP
-.B random-enabled
-Reports whether random play is enabled.  The second field of the response line
-will be \fByes\fR or \fBno\fR.
+.B random\-enabled
+Report whether random play is enabled.
+The second field of the response line will be \fByes\fR or \fBno\fR.
 .TP
 .B recent
-Sends back the current recently-played list in a response body, one track to a
-line, the track most recently played last.  See below for the track
-information syntax.
+Send back the current recently-played list in a response body, one track to a
+line, the track most recently played last.
+See below for the track information syntax.
 .TP
 .B reconfigure
-Request that DisOrder reconfigure itself.  Only trusted users may issue this
-command.
+Request that DisOrder reconfigure itself.
+Requires the \fBadmin\fR right.
+.TP
+.B register \fIUSERNAME PASSWORD EMAIL
+Register a new user.
+Requires the \fBregister\fR right.
+The result contains a confirmation string; the user will be be able
+to log in until this has been presented back to the server via the
+\fBconfirm\fR command.
+.TP
+.B reminder \fIUSERNAME\fR
+Send a password reminder to user \fIUSERNAME\fR.
+If the user has no valid email address, or no password, or a
+reminder has been sent too recently, then no reminder will be sent.
 .TP
 .B remove \fIID\fR
-Remove the track identified by \fIID\fR.  If \fBrestrict remove\fR is enabled
-in the server's configuration then only the user that submitted the track may
-remove it.
+Remove the track identified by \fIID\fR.
+Requires one of the \fBremove mine\fR, \fBremove random\fR or
+\fBremove any\fR rights depending on how the
+track came to be added to the queue.
 .TP
-.B rescan
+.B rescan \fR[\fBwait\fR] \fR[\fBfresh\fR]
 Rescan all roots for new or obsolete tracks.
+Requires the \fBrescan\fR right.
+.IP
+If the \fBwait\fR flag is present then the response is delayed until the rescan
+completes.
+Otherwise the response arrives immediately.
+This is primarily intended for testing.
+.IP
+If the \fBfresh\fR flag is present a rescan is already underway then a second
+rescan will be started when it completes.
+The default behavior is to piggyback on the existing rescan.
+.IP
+NB that \fBfresh\fR is currently disabled in the server source, so using this
+flag will just provoke an error.
 .TP
 .B resolve \fITRACK\fR
 Resolve a track name, i.e. if this is an alias then return the real track name.
 .TP
 .B resume
 Resume the current track after a \fBpause\fR command.
+Requires the \fBpause\fR right.
+.TP
+.B revoke \fBcookie\fR
+Revoke a cookie previously created with \fBmake\-cookie\fR.
+It will not be possible to use this cookie in the future.
+.TP
+.B rtp\-address
+Report the RTP broadcast (or multicast) address, in the form \fIADDRESS
+PORT\fR.
+This command does not require authentication.
 .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
-configuration then only the user that submitted the track may scratch it.
+\fIID\fR is specified.
+Requires one of the \fBscratch mine\fR, \fBscratch random\fR or
+\fBscratch any\fR rights depending on how the track came to be
+added to the queue.
+.TP
+.B schedule-add \fIWHEN\fR \fIPRIORITY\fR \fIACTION\fR ...
+Schedule an event for the future.
+.IP
+.I WHEN
+is the time when it should happen, as \fBtime_t\fR value.
+It must refer to a time in the future.
+.IP
+.I PRIORITY
+is the event priority.
+This can be \fBnormal\fR, in which case the event will be run at startup if its
+time has past, or \fBjunk\fR in which case it will be discarded if it is found
+to be in the past at startup.
+The meaning of other values is not defined.
+.IP
+.I ACTION
+is the action to perform.
+The choice of action determines the meaning of the remaining arguments.
+Possible actions are:
+.RS
+.TP
+.B play
+Play a track.
+The next argument is the track name.
+Requires the \fBplay\fR right.
+.TP
+.B set-global
+Set a global preference.
+The next argument is the preference name and the final argument is the value to
+set it to (omit it to unset it).
+Requires the \fBglobal prefs\fR right.
+.RE
+.IP
+You need the right at the point you create the event.
+It is not possible to create scheduled events in expectation of a future change
+in rights.
+.TP
+.B schedule-del \fIEVENT\fR
+Deletes a scheduled event.
+Users can always delete their own scheduled events; with the \fBadmin\fR
+right you can delete any event.
+.TP
+.B schedule-get \fIEVENT\fR
+Sends the details of scheduled event \fIEVENT\fR in a response body.
+Each line is a pair of strings quoted in the usual way, the first being the key
+ane the second the value.
+No particular order is used.
+.IP
+Scheduled events are considered public information.
+Right \fBread\fR is sufficient to see details of all events.
+.TP
+.B schedule-list
+Sends the event IDs of all scheduled events in a response body, in no
+particular order.
+Use \fBschedule-get\fR to get the details of each event.
 .TP
 .B search \fITERMS\fR
-Search for tracks matching the search terms.  The results are put in a response
-body, one to a line.
+Search for tracks matching the search terms.
+The results are put in a response body, one to a line.
 .IP
 The search string is split in the usual way, with quoting supported, into a
-list of terms.  Only tracks matching all terms are included in the results.
+list of terms.
+Only tracks matching all terms are included in the results.
 .IP
 Any terms of the form \fBtag:\fITAG\fR limits the search to tracks with that
 tag.
@@ -206,9 +370,11 @@ allow searching for phrases.
 .TP
 .B \fBset\fR \fITRACK\fR \fIPREF\fR \fIVALUE\fR
 Set a preference.
+Requires the \fBprefs\fR right.
 .TP
-.B set-global \fIKEY\fR \fIVALUE\fR
+.B set\-global \fIKEY\fR \fIVALUE\fR
 Set a global preference.
+Requires the \fBglobal prefs\fR right.
 .TP
 .B stats
 Send server statistics in plain text in a response body.
@@ -218,19 +384,23 @@ Send the list of currently known tags in a response body.
 .TP
 .B \fBunset\fR \fITRACK\fR \fIPREF\fR
 Unset a preference.
+Requires the \fBprefs\fR right.
 .TP
-.B \fBunset-global\fR \fIKEY\fR
+.B \fBunset\-global\fR \fIKEY\fR
 Unset a global preference.
+Requires the \fBglobal prefs\fR right.
 .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.
+.B user \fIUSERNAME\fR \fIRESPONSE\fR
+Authenticate as user \fIUSERNAME\fR.
+See
+.B AUTHENTICATION
+below.
+.TP
+.B userinfo \fIUSERNAME PROPERTY
+Get a user property.
+.TP
+.B users
+Send the list of currently known users in a response body.
 .TP
 .B version
 Send back a response with the server version as the second field.
@@ -241,11 +411,12 @@ Get or set the volume.
 With zero parameters just gets the volume and reports the left and right sides
 as the 2nd and 3rd fields of the response.
 .IP
-With one parameter sets both sides to the same value.  With two parameters sets
-each side independently.
+With one parameter sets both sides to the same value.
+With two parameters sets each side independently.
+Setting the volume requires the \fBvolume\fR right.
 .SH RESPONSES
-Responses are three-digit codes.  The first digit distinguishes errors from
-succesful responses:
+Responses are three-digit codes.
+The first digit distinguishes errors from succesful responses:
 .TP
 .B 2
 Operation succeeded.
@@ -256,8 +427,11 @@ Operation failed.
 The second digit breaks down the origin of the response:
 .TP
 .B 0
-Generic responses not specific to the handling of the command.  Mostly this is
-parse errors.
+Generic responses not specific to the handling of the command.
+Mostly this is parse errors.
+.TP
+.B 1
+51x errors indicate that the user had insufficient rights for the command.
 .TP
 .B 3
 Authentication responses.
@@ -280,27 +454,38 @@ Text part is a potentially variable result.
 Text part is just commentary; a dot-stuffed body follows.
 .TP
 .B 4
-Text part is just commentary; an indefinite dot-stuffed body follows.  (Used
-for \fBlog\fR.)
+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.)
+.B 5
+Used with "normal" errors, for instance a preference not being found.
+The text part is commentary.
 .TP
 .B 9
 The text part is just commentary (but would normally be a response for this
 command) e.g. \fBplaying\fR.
+.PP
+Result strings (not bodies) intended for machine parsing (i.e. xx1 and xx2
+responses) are quoted.
 .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 a protocol generation, an algorithm name and a
+challenge encoded in hex, all separated by whitespace.
+.PP
+The current protocol generation is \fB2\fR.
 .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 possible algorithms are (currently) \fBsha1\fR, \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
-following meanings:
+pairs of fields.
+The first is a name, the second a value.
+The names have the following meanings:
 .TP 12
 .B expected
 The time the track is expected to be played at.
@@ -314,19 +499,34 @@ The time the track was played at.
 .B scratched
 The user that scratched the track.
 .TP
+.B origin
+The origin of the track.  Valid origins are:
+.RS
+.TP 12
+.B adopted
+The track was originally randomly picked but has been adopted by a user.
+.TP
+.B picked
+The track was picked by a user.
+.TP
+.B random
+The track was randomly picked.
+.TP
+.B scheduled
+The track was played from a scheduled action.
+.TP
+.B scratch
+The track is a scratch sound.
+.RE
+.TP
 .B state
-The current track state.  Valid states are:
+The current track state.
+Valid states are:
 .RS
 .TP 12
 .B failed
 The player failed (exited with nonzero status but wasn't scratched).
 .TP
-.B isscratch
-The track is actually a scratch.
-.TP
-.B no_player
-No player could be found for the track.
-.TP
 .B ok
 The track was played without any problems.
 .TP
@@ -336,6 +536,9 @@ The track was scratched.
 .B started
 The track is currently playing.
 .TP
+.B paused
+Track is playing but paused.
+.TP
 .B unplayed
 In the queue, hasn't been played yet.
 .TP
@@ -354,12 +557,15 @@ The time the track was added to the queue.
 .TP
 .B wstat
 The wait status of the player in decimal.
+.PP
+Note that \fBorigin\fR is new with DisOrder 4.3, and obsoletes some old
+\fBstate\fR values.
 .SH NOTES
 Times are decimal integers using the server's \fBtime_t\fR.
 .PP
 For file listings, the regexp applies to the basename of the returned file, not
-the whole filename, and letter case is ignored.  \fBpcrepattern\fR(3) describes
-the regexp syntax.
+the whole filename, and letter case is ignored.
+\fBpcrepattern\fR(3) describes the regexp syntax.
 .PP
 Filenames are in UTF-8 even if the collection they come from uses some other
 encoding - if you want to access the real file (in such cases as the filenames
@@ -367,8 +573,12 @@ actually correspond to a real file) you'll have to convert to whatever the
 right encoding is.
 .SH "EVENT LOG"
 The event log consists of lines starting with a hexadecimal timestamp and a
-keyword followed by (optionally) parameters.  The parameters are quoted in the
-usual DisOrder way.  Currently the following keywords are used:
+keyword followed by (optionally) parameters.
+The parameters are quoted in the usual DisOrder way.
+Currently the following keywords are used:
+.TP
+.B adopted \fIID\fR \fIUSERNAME\fR
+\fIUSERNAME\fR adopted track \fIID\fR.
 .TP
 .B completed \fITRACK\fR
 Completed playing \fITRACK\fR
@@ -376,11 +586,11 @@ Completed playing \fITRACK\fR
 .B failed \fITRACK\fR \fIERROR\fR
 Completed playing \fITRACK\fR with an error status
 .TP
-.B moved \fIUSER\fR
-User \fIUSER\fR moved some track(s).  Further details aren't included any
-more.
+.B moved \fIUSERNAME\fR
+User \fIUSERNAME\fR moved some track(s).
+Further details aren't included any more.
 .TP
-.B playing \fITRACK\fR [\fIUSER\fR]
+.B playing \fITRACK\fR [\fIUSERNAME\fR]
 Started playing \fITRACK\fR.
 .TP
 .B queue \fIQUEUE-ENTRY\fR...
@@ -392,17 +602,25 @@ Added \fIID\fR to the recently played list.
 .B recent_removed \fIID\fR
 Removed \fIID\fR from the recently played list.
 .TP
-.B removed \fIID\fR [\fIUSER\fR]
-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).
+.B removed \fIID\fR [\fIUSERNAME\fR]
+Queue entry \fIID\fR was removed.
+This is used both for explicit removal (when \fIUSERNAME\fR is present)
+and when playing a track (when it is absent).
 .TP
-.B scratched \fITRACK\fR \fIUSER\fR
-\fITRACK\fR was scratched by \fIUSER\fR.
+.B rescanned
+A rescan completed.
+.TP
+.B scratched \fITRACK\fR \fIUSERNAME\fR
+\fITRACK\fR was scratched by \fIUSERNAME\fR.
 .TP
 .B state \fIKEYWORD\fR
-Some state change occurred.  The current set of keywords is:
+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
@@ -415,12 +633,39 @@ 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 rights_changed \fIRIGHTS\fR
+User's rights were changed.
+.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
+.TB
+.B user_add \fIUSERNAME\fR
+A user was created.
+.TP
+.B user_delete \fIUSERNAME\fR
+A user was deleted.
+.TP
+.B user_edit \fIUSERNAME\fR \fIPROPERTY\fR
+Some property of a user was edited.
+.TP
+.B user_confirm \fIUSERNAME\fR
+A user's login was confirmed (via the web interface).
 .TP
 .B volume \fILEFT\fR \fIRIGHT\fR
 The volume changed.
@@ -429,6 +674,74 @@ The volume changed.
 is as defined in
 .B "TRACK INFORMATION"
 above.
+.PP
+The \fBuser-*\fR messages are only sent to admin users, and are not sent over
+non-local connections unless \fBremote_userman\fR is enabled.
+.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 TILDE,
+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),