Correct documentation for 'revoke'.

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index f4c5b2fbfd446c744c484383229d0ef1f5f0aa71..58a7e8f078cbe39d47652b5489db195afb11e15f 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.


@@ -66,7 +75,8 @@ If \fIREGEXP\fR is present only matching files and directories are returned.
 .B confirm \fICONFIRMATION
 Confirm user registration.
 \fICONFIRMATION\fR is as returned from \fBregister\fR below.
 .B confirm \fICONFIRMATION
 Confirm user registration.
 \fICONFIRMATION\fR is as returned from \fBregister\fR below.

-This command can be used without logging in.
+This command logs the user in.
+The response contains the logged-in username.

 .TP
 .B cookie \fICOOKIE
 Log a user back in using a cookie created with \fBmake\-cookie\fR.
 .TP
 .B cookie \fICOOKIE
 Log a user back in using a cookie created with \fBmake\-cookie\fR.


@@ -113,7 +123,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.


@@ -162,7 +172,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


@@ -198,6 +208,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


@@ -206,6 +226,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


@@ -236,6 +294,11 @@ 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
 .B register \fIUSERNAME PASSWORD EMAIL
 Register a new user.
 .TP
 .B register \fIUSERNAME PASSWORD EMAIL
 Register a new user.


@@ -278,9 +341,9 @@ Resolve a track name, i.e. if this is an alias then return the real track name.
 Resume the current track after a \fBpause\fR command.
 Requires the \fBpause\fR right.
 .TP
 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.
+.B revoke
+Revoke the current login's cookie.
+It will not be possible to use the cookie in the future.

 .TP
 .B rtp\-address
 Report the RTP broadcast (or multicast) address, in the form \fIADDRESS
 .TP
 .B rtp\-address
 Report the RTP broadcast (or multicast) address, in the form \fIADDRESS


@@ -374,6 +437,10 @@ Requires the \fBprefs\fR right.
 Set a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP
 Set a global preference.
 Requires the \fBglobal prefs\fR right.
 .TP

+.B shutdown
+Requests server shutdown.
+Requires the \fBadmin\fR right.
+.TP

 .B stats
 Send server statistics in plain text in a response body.
 .TP
 .B stats
 Send server statistics in plain text in a response body.
 .TP


@@ -414,7 +481,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.


@@ -497,6 +564,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:


@@ -505,12 +592,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


@@ -520,6 +601,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


@@ -538,6 +622,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


@@ -555,12 +642,18 @@ 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 global_pref \fIPREF\fR [\fIVALUE\fR]
+A global preference was set or unset.
+.TP

 .B moved \fIUSERNAME\fR
 User \fIUSERNAME\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.


@@ -568,6 +661,21 @@ Further details aren't included any more.
 .B playing \fITRACK\fR [\fIUSERNAME\fR]
 Started playing \fITRACK\fR.
 .TP
 .B playing \fITRACK\fR [\fIUSERNAME\fR]
 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


@@ -620,6 +728,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


@@ -627,6 +738,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


@@ -634,6 +757,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