X-Git-Url: https://git.distorted.org.uk/~mdw/disorder/blobdiff_plain/5c102112f4a3b71145bf42091d93d5d353d2b143..531a8ecd1dc7d4f827db9a2fc2090d9c4878ea17:/doc/disorder_protocol.5.in diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in index 5a8a481..f3cb615 100644 --- a/doc/disorder_protocol.5.in +++ b/doc/disorder_protocol.5.in @@ -1,20 +1,18 @@ .\" .\" 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 . .\" .TH disorder_protocol 5 .SH NAME @@ -66,6 +64,10 @@ 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] 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. @@ -73,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. -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. @@ -120,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 -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. @@ -169,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. -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 @@ -205,6 +208,16 @@ Add a track to the queue. 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 @@ -220,6 +233,7 @@ Requires permission to modify that playlist and the \fBplay\fR right. .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. @@ -280,6 +294,11 @@ See below for the track information syntax. .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. @@ -458,7 +477,7 @@ 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: +The first digit distinguishes errors from successful responses: .TP .B 2 Operation succeeded. @@ -541,6 +560,26 @@ 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: @@ -549,12 +588,6 @@ Valid states are: .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 @@ -564,6 +597,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 @@ -582,6 +618,9 @@ 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 @@ -599,12 +638,18 @@ 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 .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.