chiark / gitweb /
remove become from client; more docs updates
[disorder] / doc / disorder_protocol.5.in
CommitLineData
460b9539 1.\"
2.\" Copyright (C) 2004, 2005, 2006 Richard Kettlewell
3.\"
4.\" This program is free software; you can redistribute it and/or modify
5.\" it under the terms of the GNU General Public License as published by
6.\" the Free Software Foundation; either version 2 of the License, or
7.\" (at your option) any later version.
8.\"
9.\" This program is distributed in the hope that it will be useful, but
10.\" WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12.\" General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with this program; if not, write to the Free Software
16.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17.\" USA
18.\"
19.TH disorder_protocol 5
20.SH NAME
21disorder_protocol \- DisOrder communication protocol
22.SH DESCRIPTION
23The DisOrder client and server communicate via the protocol described
24in this man page.
25.PP
26The protocol is liable to change without notice. You are recommended to check
27the implementation before believing this document.
28.SH "GENERAL SYNTAX"
f9635e06
RK
29Everything is encoded using UTF-8. See
30.B "CHARACTER ENCODING"
31below for more detail on character encoding issues.
460b9539 32.PP
f9635e06
RK
33Commands and responses consist of a line perhaps followed (depending on the
34command or response) by a body.
460b9539 35.PP
36The line syntax is the same as described in \fBdisorder_config\fR(5) except
37that comments are prohibited.
38.PP
39Bodies borrow their syntax from RFC821; they consist of zero or more ordinary
40lines, with any initial full stop doubled up, and are terminated by a line
41consisting of a full stop and a line feed.
42.SH COMMANDS
43Commands always have a command name as the first field of the line; responses
44always have a 3-digit response code as the first field. See below for more
45details about this field.
46.PP
47All commands require the connection to have been already authenticated unless
eb5dc014
RK
48stated otherwise. If not stated otherwise, the \fBread\fR right is sufficient
49to execute the command.
460b9539 50.PP
51Neither commands nor responses have a body unless stated otherwise.
52.TP
eb5dc014
RK
53.B adduser \fIUSERNAME PASSWORD
54Creates a new user with the given username and password. Requires the
55\fBadmin\fR right, and only works on local connections.
56.TP
460b9539 57.B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
58Lists all the files and directories in \fIDIRECTORY\fR in a response body.
59If \fIREGEXP\fR is present only matching files and directories are returned.
60.TP
eb5dc014
RK
61.B cookie \fICOOKIE
62Log a user back in using a cookie created with \fBmake-cookie\fR.
63.TP
64.B deluser \fIUSERNAME
65Deletes the named user. Requires the \fBadmin\fR right, and only works on
66local connections.
460b9539 67.TP
68.B dirs \fIDIRECTORY\fR [\fIREGEXP\fR]
69Lists all the directories in \fIDIRECTORY\fR in a response body.
70If \fIREGEXP\fR is present only matching directories are returned.
71.TP
72.B disable \fR[\fBnow\fR]
73Disables further playing. If the optional \fBnow\fR argument is present then
eb5dc014
RK
74the current track is stopped. Requires the \fBglobal prefs\fR right.
75.TP
76.B edituser \fIUSERNAME PROPERTY VALUE
77Sets a user property. With the \fBadmin\fR right any username and property may
78be specified. Otherwise the \fBuserinfo\fR right is required and only the
79\fBemail\fR and \fBpassword\fR properties may be set.
460b9539 80.TP
81.B enable
eb5dc014
RK
82Re-enables further playing, and is the opposite of \fBdisable\fR. Requires the
83\fBglobal prefs\fR right.
460b9539 84.TP
85.B enabled
86Reports whether playing is enabled. The second field of the response line will
87be \fByes\fR or \fBno\fR.
88.TP
89.B exists \fITRACK\fR
90Reports whether the named track exists. The second field of the response line
91will be \fByes\fR or \fBno\fR.
92.TP
93.B files \fIDIRECTORY\fR [\fIREGEXP\fR]
94Lists all the files in \fIDIRECTORY\fR in a response body.
95If \fIREGEXP\fR is present only matching files are returned.
96.TP
97.B get \fITRACK\fR \fIPREF\fR
98Gets a preference value. On success the second field of the response line will
99have the value.
fb1bc1f5
RK
100.IP
101If the track or preference do not exist then the response code is 555.
460b9539 102.TP
103.B get-global \fIKEY\fR
104Get a global preference.
fb1bc1f5
RK
105.IP
106If the preference does not exist then the response code is 555.
460b9539 107.TP
108.B length \fITRACK\fR
109Gets the length of the track in seconds. On success the second field of the
110response line will have the value.
111.TP
112.B log
397ef7bb
RK
113Sends event log messages in a response body. The command will never terminate.
114Any further data sent to the server will be discarded (explicitly; i.e. it will
115not accumulate in a buffer somewhere).
460b9539 116.IP
117See \fBEVENT LOG\fR below for more details.
118.TP
eb5dc014
RK
119.B make-cookie
120Returns an opaque string that can be used by the \fBcookie\fR command to log
121this user back in on another connection (until the cookie expires).
122.TP
460b9539 123.B move \fITRACK\fR \fIDELTA\fR
124Move a track in the queue. The track may be identified by ID (preferred) or
125name (which might cause confusion if it's there twice). \fIDELTA\fR should be
126an negative or positive integer and indicates how many steps towards the head
127of the queue the track should be moved.
eb5dc014
RK
128.IP
129Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
130depending on how the track came to be added to the queue.
460b9539 131.TP
132.B moveafter \fITARGET\fR \fIID\fR ...
133Move all the tracks in the \fIID\fR list after ID \fITARGET\fR. If
134\fITARGET\fR is the empty string then the listed tracks are put at the head of
135the queue. If \fITARGET\fR is listed in the ID list then the tracks are moved
136to just after the first non-listed track before it, or to the head if there is
137no such track.
eb5dc014
RK
138.IP
139Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
140depending on how the tracks came to be added to the queue.
460b9539 141.TP
2a10b70b
RK
142.B new \fR[\fIMAX\fR]
143Sends the most recently added \fIMAX\fR tracks in a response body. If the
144argument is ommitted, all recently added tracks are listed.
145.TP
7858930d 146.B nop
147Do nothing. Used by
148.BR disobedience (1)
eb5dc014 149as a keepalive measure. This command does not require authentication.
7858930d 150.TP
460b9539 151.B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
152Get a track name part. Returns an empty string if a name part cannot be
153constructed.
154.IP
155.I CONTEXT
156is one of
157.B sort
158or
159.B display
160and
161.I PART
162is usually one of
163.BR artist ,
164.B album
165or
166.BR title .
167.TP
168.B pause
eb5dc014 169Pause the current track. Requires the \fBpause\R right.
460b9539 170.TP
171.B play \fITRACK\fR
81e440ce 172Add a track to the queue. The response contains the queue ID of the track.
eb5dc014 173Requires the \fBplay\fR right.
460b9539 174.TP
175.B playing
176Reports what track is playing.
177.IP
178If the response is \fB252\fR then the rest of the response line consists of
179track information (see below).
180.IP
181If the response is \fB259\fR then nothing is playing.
182.TP
183.B prefs \fBTRACK\fR
184Sends back the preferences for \fITRACK\fR in a response body.
185Each line of the response has the usual line syntax, the first field being the
186name of the pref and the second the value.
187.TP
188.B queue
189Sends back the current queue in a response body, one track to a line, the track
190at the head of the queue (i.e. next to be be played) first. See below for the
191track information syntax.
192.TP
193.B random-disable
eb5dc014
RK
194Disable random play (but don't stop the current track). Requires the \fBglobal
195prefs\fR right.
460b9539 196.TP
197.B random-enable
eb5dc014 198Enable random play. Requires the \fBglobal prefs\fR right.
460b9539 199.TP
200.B random-enabled
201Reports whether random play is enabled. The second field of the response line
202will be \fByes\fR or \fBno\fR.
203.TP
204.B recent
205Sends back the current recently-played list in a response body, one track to a
206line, the track most recently played last. See below for the track
207information syntax.
208.TP
209.B reconfigure
eb5dc014 210Request that DisOrder reconfigure itself. Requires the \fBadmin\fR right.
460b9539 211command.
212.TP
213.B remove \fIID\fR
eb5dc014
RK
214Remove the track identified by \fIID\fR. Requires one of the \fBremove
215mine\fR, \fBremove random\fR or \fBremove any\fR rights depending on how the
216track came to be added to the queue.
460b9539 217.TP
218.B rescan
eb5dc014 219Rescan all roots for new or obsolete tracks. Requires the \fBrescan\fR right.
460b9539 220.TP
221.B resolve \fITRACK\fR
222Resolve a track name, i.e. if this is an alias then return the real track name.
223.TP
224.B resume
eb5dc014
RK
225Resume the current track after a \fBpause\fR command. Requires the \fBpause\fR
226right.
227.TP
228.B revoke \fBcookie\fR
229Revokes a cookie previously created with \fBmake-cookie\fR. It will not be
230possible to use this cookie in the future.
460b9539 231.TP
ca831831
RK
232.B rtp-address
233Reports the RTP broadcast (or multicast) address, in the form \fIADDRESS
eb5dc014 234PORT\fR. This command does not require authentication.
ca831831 235.TP
460b9539 236.B scratch \fR[\fIID\fR]
237Remove the track identified by \fIID\fR, or the currently playing track if no
eb5dc014
RK
238\fIID\fR is specified. Requires one of the \fBscratch mine\fR, \fBscratch
239random\fR or \fBscratch any\fR rights depending on how the track came to be
240added to the queue.
460b9539 241.TP
242.B search \fITERMS\fR
243Search for tracks matching the search terms. The results are put in a response
244body, one to a line.
245.IP
246The search string is split in the usual way, with quoting supported, into a
247list of terms. Only tracks matching all terms are included in the results.
248.IP
249Any terms of the form \fBtag:\fITAG\fR limits the search to tracks with that
250tag.
251.IP
252All other terms are interpreted as individual words which must be present in
253the track name.
254.IP
255Spaces in terms don't currently make sense, but may one day be interpreted to
256allow searching for phrases.
257.TP
258.B \fBset\fR \fITRACK\fR \fIPREF\fR \fIVALUE\fR
eb5dc014 259Set a preference. Requires the \fBprefs\fR right.
460b9539 260.TP
261.B set-global \fIKEY\fR \fIVALUE\fR
eb5dc014 262Set a global preference. Requires the \fBglobal prefs\fR right.
460b9539 263.TP
264.B stats
265Send server statistics in plain text in a response body.
266.TP
267.B \fBtags\fR
268Send the list of currently known tags in a response body.
269.TP
270.B \fBunset\fR \fITRACK\fR \fIPREF\fR
eb5dc014 271Unset a preference. Requires the \fBprefs\fR right.
460b9539 272.TP
273.B \fBunset-global\fR \fIKEY\fR
eb5dc014 274Unset a global preference. Requires the \fBglobal prefs\fR right.
460b9539 275.TP
276.B user \fIUSER\fR \fIRESPONSE\fR
5e3f9e08
RK
277Authenticate as \fIUSER\fR. See
278.B AUTHENTICATION
279below.
460b9539 280.TP
eb5dc014
RK
281.B users
282Sends the list of currently known users in a response body.
283.TP
460b9539 284.B version
285Send back a response with the server version as the second field.
286.TP
287.B volume \fR[\fILEFT\fR [\fIRIGHT\fR]]
288Get or set the volume.
289.IP
290With zero parameters just gets the volume and reports the left and right sides
291as the 2nd and 3rd fields of the response.
292.IP
293With one parameter sets both sides to the same value. With two parameters sets
eb5dc014 294each side independently. Setting the volume requires the \fBvolume\fR right.
460b9539 295.SH RESPONSES
296Responses are three-digit codes. The first digit distinguishes errors from
297succesful responses:
298.TP
299.B 2
300Operation succeeded.
301.TP
302.B 5
303Operation failed.
304.PP
305The second digit breaks down the origin of the response:
306.TP
307.B 0
308Generic responses not specific to the handling of the command. Mostly this is
309parse errors.
310.TP
311.B 3
312Authentication responses.
313.TP
314.B 5
315Responses specific to the handling of the command.
316.PP
317The third digit provides extra information about the response:
318.TP
319.B 0
320Text part is just commentary.
321.TP
322.B 1
323Text part is a constant result e.g. \fBversion\fR.
324.TP
325.B 2
326Text part is a potentially variable result.
327.TP
328.B 3
329Text part is just commentary; a dot-stuffed body follows.
330.TP
331.B 4
332Text part is just commentary; an indefinite dot-stuffed body follows. (Used
333for \fBlog\fR.)
334.TP
fb1bc1f5
RK
335.B 5
336Used with "normal" errors, for instance a preference not being found. The text
337part is commentary.
338.TP
460b9539 339.B 9
340The text part is just commentary (but would normally be a response for this
341command) e.g. \fBplaying\fR.
342.SH AUTHENTICATION
5e3f9e08
RK
343When a connection is made the server sends a \fB231\fR response before any
344command is received. This contains an algorithm name and a challenge encoded
345in hex.
346.PP
347Currently the algorithm name is omitted if it is \fBsha1\fR (but this will
348probably change in a future version). The other options are \fBsha256\fR,
349\fBsha384\fR and \fBsha512\fR. \fBSHA1\fR etc work as synonyms.
460b9539 350.PP
5e3f9e08
RK
351The \fBuser\fR response consists of the selected hash of the user's password
352concatenated with the challenge, encoded in hex.
460b9539 353.SH "TRACK INFORMATION"
354Track information is encoded in a line (i.e. using the usual line syntax) as
355pairs of fields. The first is a name, the second a value. The names have the
356following meanings:
357.TP 12
358.B expected
359The time the track is expected to be played at.
360.TP
361.B id
362A string uniquely identifying this queue entry.
363.TP
364.B played
365The time the track was played at.
366.TP
367.B scratched
368The user that scratched the track.
369.TP
370.B state
371The current track state. Valid states are:
372.RS
373.TP 12
374.B failed
375The player failed (exited with nonzero status but wasn't scratched).
376.TP
377.B isscratch
378The track is actually a scratch.
379.TP
380.B no_player
381No player could be found for the track.
382.TP
383.B ok
384The track was played without any problems.
385.TP
386.B scratched
387The track was scratched.
388.TP
389.B started
390The track is currently playing.
391.TP
392.B unplayed
393In the queue, hasn't been played yet.
394.TP
395.B quitting
396The track was terminated because the server is shutting down.
397.RE
398.TP
399.B submitter
400The user that submitted the track.
401.TP
402.B track
403The filename of the track.
404.TP
405.B when
406The time the track was added to the queue.
407.TP
408.B wstat
409The wait status of the player in decimal.
410.SH NOTES
411Times are decimal integers using the server's \fBtime_t\fR.
412.PP
413For file listings, the regexp applies to the basename of the returned file, not
414the whole filename, and letter case is ignored. \fBpcrepattern\fR(3) describes
415the regexp syntax.
416.PP
417Filenames are in UTF-8 even if the collection they come from uses some other
418encoding - if you want to access the real file (in such cases as the filenames
419actually correspond to a real file) you'll have to convert to whatever the
420right encoding is.
421.SH "EVENT LOG"
422The event log consists of lines starting with a hexadecimal timestamp and a
423keyword followed by (optionally) parameters. The parameters are quoted in the
424usual DisOrder way. Currently the following keywords are used:
425.TP
426.B completed \fITRACK\fR
427Completed playing \fITRACK\fR
428.TP
429.B failed \fITRACK\fR \fIERROR\fR
430Completed playing \fITRACK\fR with an error status
431.TP
432.B moved \fIUSER\fR
433User \fIUSER\fR moved some track(s). Further details aren't included any
434more.
435.TP
436.B playing \fITRACK\fR [\fIUSER\fR]
437Started playing \fITRACK\fR.
438.TP
439.B queue \fIQUEUE-ENTRY\fR...
440Added \fITRACK\fR to the queue.
441.TP
442.B recent_added \fIQUEUE-ENTRY\fR...
443Added \fIID\fR to the recently played list.
444.TP
445.B recent_removed \fIID\fR
446Removed \fIID\fR from the recently played list.
447.TP
448.B removed \fIID\fR [\fIUSER\fR]
449Queue entry \fIID\fR was removed. This is used both for explicit removal (when
450\fIUSER\fR is present) and when playing a track (when it is absent).
451.TP
e025abff
RK
452.B rescanned
453A rescan completed.
454.TP
460b9539 455.B scratched \fITRACK\fR \fIUSER\fR
456\fITRACK\fR was scratched by \fIUSER\fR.
457.TP
458.B state \fIKEYWORD\fR
459Some state change occurred. The current set of keywords is:
460.RS
461.TP
5abe307a
RK
462.B completed
463The current track completed successfully.
464.TP
460b9539 465.B disable_play
466Playing was disabled.
467.TP
468.B disable_random
469Random play was disabled.
470.TP
471.B enable_play
472Playing was enabled.
473.TP
474.B enable_random
475Random play was enabled.
476.TP
5abe307a
RK
477.B failed
478The current track failed.
479.TP
460b9539 480.B pause
481The current track was paused.
482.TP
5abe307a
RK
483.B playing
484A track started playing.
485.TP
460b9539 486.B resume
487The current track was resumed.
5abe307a
RK
488.TP
489.B scratched
490The current track was scratched.
491.PP
492To simplify client implementation, \fBstate\fR commands reflecting the current
493state are sent at the start of the log.
460b9539 494.RE
495.TP
496.B volume \fILEFT\fR \fIRIGHT\fR
497The volume changed.
498.PP
499.IR QUEUE-ENTRY ...
500is as defined in
501.B "TRACK INFORMATION"
502above.
f9635e06
RK
503.SH "CHARACTER ENCODING"
504All data sent by both server and client is encoded using UTF-8. Moreover it
505must be valid UTF-8, i.e. non-minimal sequences are not permitted, nor are
506surrogates, nor are code points outside the Unicode code space.
507.PP
508There are no particular normalization requirements on either side of the
509protocol. The server currently converts internally to NFC, the client must
510normalize the responses returned if it needs some normalized form for further
511processing.
512.PP
513The various characters which divide up lines may not be followed by combining
514characters. For instance all of the following are prohibited:
515.TP
516.B o
517LINE FEED followed by a combining character. For example the sequence
518LINE FEED, COMBINING GRAVE ACCENT is never permitted.
519.TP
520.B o
521APOSTROPHE or QUOTATION MARK followed by a combining character when used to
522delimit fields. For instance a line starting APOSTROPHE, COMBINING CEDILLA
523is prohibited.
524.IP
525Note that such sequences are not prohibited when the quote character cannot be
526interpreted as a field delimiter. For instance APOSTROPHE, REVERSE SOLIDUS,
527APOSTROPHE, COMBINING CEDILLA, APOSTROPHE would be permitted.
528.TP
529.B o
530REVERSE SOLIDUS (BACKSLASH) followed by a combining character in a quoted
531string when it is the first character of an escape sequence. For instance a
532line starting APOSTROPHE, REVERSE SOLIDUS, COMBINING TILDE is prohibited.
533.IP
534As above such sequences are not prohibited when the character is not being used
535to start an escape sequence. For instance APOSTROPHE, REVERSE SOLIDUS,
536REVERSE SOLIDS, COMBINING TILDER, APOSTROPHE is permitted.
537.TP
538.B o
539Any of the field-splitting whitespace characters followed by a combining
540character when not part of a quoted field. For instance a line starting COLON,
541SPACE, COMBINING CANDRABINDU is prohibited.
542.IP
543As above non-delimiter uses are fine.
544.TP
545.B o
546The FULL STOP characters used to quote or delimit a body.
547.PP
548Furthermore none of these characters are permitted to appear in the context of
549a canonical decomposition (i.e. they must still be present when converted to
550NFC). In practice however this is not an issue in Unicode 5.0.
551.PP
552These rules are consistent with the observation that the split() function is
553essentially a naive ASCII parser. The implication is not that these sequences
554never actually appear in the protocol, merely that the server is not required
555to honor them in any useful way nor be consistent between versions: in current
556versions the result will be lines and fields that start with combining
557characters and are not necessarily split where you expect, but future versions
558may remove them, reject them or ignore some or all of the delimiters that have
559following combining characters, and no notice will be given of any change.
460b9539 560.SH "SEE ALSO"
561\fBdisorder\fR(1),
562\fBtime\fR(2),
563\fBdisorder\fR(3),
564\fBpcrepattern\fR(3)
565\fBdisorder_config\fR(5),
566\fBdisorderd\fR(8),
567\fButf8\fR(7)
568.\" Local Variables:
569.\" mode:nroff
570.\" fill-column:79
571.\" End: