Minor Lintian fixes

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index 24ad5e834796b233b0214ac290f2e08197b10350..bb95ff01e584ebaa68b842e23e1f26769ae28263 100644 (file)
--- a/doc/disorder_protocol.5.in
+++ b/doc/disorder_protocol.5.in
@@ -1,20 +1,18 @@
 .\"
 .\" Copyright (C) 2004-2008 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
 .\" 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.
 .\" (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
 .\" 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
 .\"
 .TH disorder_protocol 5
 .SH NAME


@@ -40,6 +38,15 @@ that comments are prohibited.
 Bodies borrow their syntax from RFC821; they consist of zero or more ordinary
 lines, with any initial full stop doubled up, and are terminated by a line
 consisting of a full stop and a line feed.
 Bodies borrow their syntax from RFC821; they consist of zero or more ordinary
 lines, with any initial full stop doubled up, and are terminated by a line
 consisting of a full stop and a line feed.

+.PP
+Commands only have a body if explicitly stated below.
+If they do have a body then the body should always be sent immediately;
+unlike (for instance) the SMTP "DATA" command there is no intermediate step
+where the server asks for the body to be sent.
+.PP
+Replies also only have a body if stated below.
+The presence of a reply body can always be inferred from the response code;
+if the last digit is a 3 then a body is present, otherwise it is not.

 .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.
 .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.


@@ -49,8 +56,6 @@ 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.
 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.
 .TP
 .B adduser \fIUSERNAME PASSWORD \fR[\fIRIGHTS\fR]
 Create a new user with the given username and password.


@@ -59,6 +64,10 @@ then the \fBdefault_rights\fR setting applies instead.
 Requires the \fBadmin\fR right, and only works on local
 connections.
 .TP
 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]
 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.
 .B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
 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.


@@ -91,6 +100,10 @@ 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.
 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-enable further playing, and is the opposite of \fBdisable\fR.
 .TP
 .B enable
 Re-enable further playing, and is the opposite of \fBdisable\fR.


@@ -109,7 +122,7 @@ 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
 If \fIREGEXP\fR is present only matching files are returned.
 .TP
 .B get \fITRACK\fR \fIPREF\fR

-Getsa preference value.
+Gets a 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.
 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.


@@ -158,7 +171,7 @@ 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.
 .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
+If the argument is omitted, the \fBnew_max\fR most recent tracks are

 listed (see \fBdisorder_config\fR(5)).
 .TP
 .B nop
 listed (see \fBdisorder_config\fR(5)).
 .TP
 .B nop


@@ -194,6 +207,16 @@ Add a track to the queue.
 The response contains the queue ID of the track.
 Requires the \fBplay\fR right.
 .TP
 The response contains the queue ID of the track.
 Requires the \fBplay\fR right.
 .TP

+.B playafter \fITARGET\fR \fITRACK\fR ...
+Add all the tracks in the \fITRACK\fR list to the queue after \fITARGET\fR
+(which should be a track ID).
+If \fITARGET\fR is the empty string then the listed tracks are put
+at the head of the queue.
+.IP
+Currently the success result does \fInot\fR include the new track IDs.
+.IP
+Requires the \fBplay\fR right.
+.TP

 .B playing
 Report what track is playing.
 .IP
 .B playing
 Report what track is playing.
 .IP


@@ -202,6 +225,44 @@ track information (see below).
 .IP
 If the response is \fB259\fR then nothing is playing.
 .TP
 .IP
 If the response is \fB259\fR then nothing is playing.
 .TP

+.B playlist-delete \fIPLAYLIST\fR
+Delete a playlist.
+Requires permission to modify that playlist and the \fBplay\fR right.
+.TP
+.B playlist-get \fIPLAYLIST\fR
+Get the contents of a playlist, in a response body.
+Requires permission to read that playlist and the \fBread\fR right.
+If the playlist does not exist the response is 555.
+.TP
+.B playlist-get-share \fIPLAYLIST\fR
+Get the sharing status of a playlist.
+The result will be \fBpublic\fR, \fBprivate\fR or \fBshared\fR.
+Requires permission to read that playlist and the \fBread\fR right.
+.TP
+.B playlist-lock \fIPLAYLIST\fR
+Lock a playlist.
+Requires permission to modify that playlist and the \fBplay\fR right.
+Only one playlist may be locked at a time on a given connection and the lock
+automatically expires when the connection is closed.
+.TP
+.B playlist-set \fIPLAYLIST\fR
+Set the contents of a playlist.
+The new contents should be supplied in a command body.
+Requires permission to modify that playlist and the \fBplay\fR right.
+The playlist must be locked.
+.TP
+.B playlist-set-share \fIPLAYLIST\fR \fISHARE\fR
+Set the sharing status of a playlist to
+\fBpublic\fR, \fBprivate\fR or \fBshared\fR.
+Requires permission to modify that playlist and the \fBplay\fR right.
+.TP
+.B playlist-unlock\fR
+Unlock the locked playlist.
+.TP
+.B playlists
+List all playlists that this connection has permission to read.
+Requires the \fBread\fR right.
+.TP

 .B prefs \fBTRACK\fR
 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
 .B prefs \fBTRACK\fR
 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


@@ -232,16 +293,21 @@ See below for the track information syntax.
 .B reconfigure
 Request that DisOrder reconfigure itself.
 Requires the \fBadmin\fR right.
 .B reconfigure
 Request that DisOrder reconfigure itself.
 Requires the \fBadmin\fR right.

+.IP
+Not all configuration options can be modified during the lifetime of the
+server; of those that can't, some will just be ignored if they change while
+others will cause the new configuration to be rejected.
+See \fBdisorder_config\fR(5) for details.

 .TP
 .TP

-.B register \fIUSER PASSWORD EMAIL
+.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
 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 \fIUSER\fR
-Send a password reminder to \fIUSER\fR.
+.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
 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


@@ -251,9 +317,21 @@ 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
 \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.
 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 resolve \fITRACK\fR
 Resolve a track name, i.e. if this is an alias then return the real track name.


@@ -278,6 +356,61 @@ 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
 \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.
 .B search \fITERMS\fR
 Search for tracks matching the search terms.
 The results are put in a response body, one to a line.


@@ -317,13 +450,13 @@ Requires the \fBprefs\fR right.
 Unset a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP
 Unset a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP

-.B user \fIUSER\fR \fIRESPONSE\fR
-Authenticate as \fIUSER\fR.
+.B user \fIUSERNAME\fR \fIRESPONSE\fR
+Authenticate as user \fIUSERNAME\fR.

 See
 .B AUTHENTICATION
 below.
 .TP
 See
 .B AUTHENTICATION
 below.
 .TP

-.B userinfo \fIUSER PROPERTY
+.B userinfo \fIUSERNAME PROPERTY

 Get a user property.
 .TP
 .B users
 Get a user property.
 .TP
 .B users


@@ -343,7 +476,7 @@ With two parameters sets each side independently.
 Setting the volume requires the \fBvolume\fR right.
 .SH RESPONSES
 Responses are three-digit codes.
 Setting the volume requires the \fBvolume\fR right.
 .SH RESPONSES
 Responses are three-digit codes.

-The first digit distinguishes errors from succesful responses:
+The first digit distinguishes errors from successful responses:

 .TP
 .B 2
 Operation succeeded.
 .TP
 .B 2
 Operation succeeded.


@@ -426,6 +559,26 @@ The time the track was played at.
 .B scratched
 The user that scratched the track.
 .TP
 .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:
 .B state
 The current track state.
 Valid states are:


@@ -434,12 +587,6 @@ Valid states are:
 .B failed
 The player failed (exited with nonzero status but wasn't scratched).
 .TP
 .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
 .B ok
 The track was played without any problems.
 .TP


@@ -449,6 +596,9 @@ The track was scratched.
 .B started
 The track is currently playing.
 .TP
 .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
 .B unplayed
 In the queue, hasn't been played yet.
 .TP


@@ -467,6 +617,9 @@ The time the track was added to the queue.
 .TP
 .B wstat
 The wait status of the player in decimal.
 .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
 .SH NOTES
 Times are decimal integers using the server's \fBtime_t\fR.
 .PP


@@ -484,19 +637,37 @@ keyword followed by (optionally) parameters.
 The parameters are quoted in the usual DisOrder way.
 Currently the following keywords are used:
 .TP
 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
 .TP
 .B failed \fITRACK\fR \fIERROR\fR
 Completed playing \fITRACK\fR with an error status
 .TP
 .B completed \fITRACK\fR
 Completed playing \fITRACK\fR
 .TP
 .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).
+.B moved \fIUSERNAME\fR
+User \fIUSERNAME\fR moved some track(s).

 Further details aren't included any more.
 .TP
 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
 Started playing \fITRACK\fR.
 .TP

+.B playlist_created \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is created.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_deleted \fIPLAYLIST\fR
+Sent when a playlist is deleted.
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP
+.B playlist_modified \fIPLAYLIST\fR \fISHARING\fR
+Sent when a playlist is modified (either its contents or its sharing status).
+For private playlists this is intended to be sent only to the owner (but
+this is not currently implemented).
+.TP

 .B queue \fIQUEUE-ENTRY\fR...
 Added \fITRACK\fR to the queue.
 .TP
 .B queue \fIQUEUE-ENTRY\fR...
 Added \fITRACK\fR to the queue.
 .TP


@@ -506,16 +677,16 @@ Added \fIID\fR to the recently played list.
 .B recent_removed \fIID\fR
 Removed \fIID\fR from the recently played list.
 .TP
 .B recent_removed \fIID\fR
 Removed \fIID\fR from the recently played list.
 .TP

-.B removed \fIID\fR [\fIUSER\fR]
+.B removed \fIID\fR [\fIUSERNAME\fR]

 Queue entry \fIID\fR was removed.
 Queue entry \fIID\fR was removed.

-This is used both for explicit removal (when \fIUSER\fR is present)
+This is used both for explicit removal (when \fIUSERNAME\fR is present)

 and when playing a track (when it is absent).
 .TP
 .B rescanned
 A rescan completed.
 .TP
 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.
+.B scratched \fITRACK\fR \fIUSERNAME\fR
+\fITRACK\fR was scratched by \fIUSERNAME\fR.

 .TP
 .B state \fIKEYWORD\fR
 Some state change occurred.
 .TP
 .B state \fIKEYWORD\fR
 Some state change occurred.


@@ -549,6 +720,9 @@ A track started playing.
 .B resume
 The current track was resumed.
 .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
 .B scratched
 The current track was scratched.
 .PP


@@ -556,6 +730,18 @@ To simplify client implementation, \fBstate\fR commands reflecting the current
 state are sent at the start of the log.
 .RE
 .TP
 state are sent at the start of the log.
 .RE
 .TP

+.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.
 .PP
 .B volume \fILEFT\fR \fIRIGHT\fR
 The volume changed.
 .PP


@@ -563,6 +749,9 @@ The volume changed.
 is as defined in
 .B "TRACK INFORMATION"
 above.
 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
 .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