Add SHELL=bash debian/rules for benefit of systems with rubbish default

[disorder] / doc / disorder_protocol.5.in

diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in
index 5a2bf839a25e5601ad66b4e84824b48979ee3f4b..b42ebd5f4ec5e0c88c7e16a2af4e44eaa07fe980 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


@@ -59,6 +57,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.


@@ -236,6 +238,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.


@@ -255,9 +262,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.


@@ -282,6 +301,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.


@@ -430,6 +504,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:


@@ -438,12 +532,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


@@ -453,6 +541,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


@@ -471,6 +562,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


@@ -488,6 +582,9 @@ 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 completed \fITRACK\fR
 Completed playing \fITRACK\fR
 .TP


@@ -553,6 +650,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


@@ -560,6 +660,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


@@ -567,6 +679,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