X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/3e3566ad03147b4c6c2b6e353853aad1eb623840..c03fbc77308bbf5c9f7fe3c64f07786a53b1a59e:/doc/disorder_protocol.5.in diff --git a/doc/disorder_protocol.5.in b/doc/disorder_protocol.5.in index 24ad5e8..bb95ff0 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 @@ -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. +.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. @@ -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. -.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. @@ -59,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. @@ -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. +.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. @@ -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 -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. @@ -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. -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 @@ -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 +.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 @@ -202,6 +225,44 @@ track information (see below). .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 @@ -232,16 +293,21 @@ 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 \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 -.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 @@ -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 -.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. @@ -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 +.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. @@ -317,13 +450,13 @@ Requires the \fBprefs\fR right. 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 -.B userinfo \fIUSER PROPERTY +.B userinfo \fIUSERNAME PROPERTY 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. -The first digit distinguishes errors from succesful responses: +The first digit distinguishes errors from successful responses: .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 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: @@ -434,12 +587,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 @@ -449,6 +596,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 @@ -467,6 +617,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 @@ -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 +.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 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 -.B playing \fITRACK\fR [\fIUSER\fR] +.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 @@ -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 removed \fIID\fR [\fIUSER\fR] +.B removed \fIID\fR [\fIUSERNAME\fR] 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 -.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. @@ -549,6 +720,9 @@ A track started playing. .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 @@ -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 +.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 @@ -563,6 +749,9 @@ 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