.\"
.\" 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 <http://www.gnu.org/licenses/>.
.\"
.TH disorder_protocol 5
.SH NAME
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.
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.
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 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.
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.
.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
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
.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 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.
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
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
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.
.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 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 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
.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
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.
.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 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
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
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
~mdw / disorder / blobdiff