chiark / gitweb /
Build fixes for GCC 4.1
[disorder] / doc / disorder_protocol.5.in
CommitLineData
460b9539 1.\"
964e027d 2.\" Copyright (C) 2004-2008 Richard Kettlewell
460b9539 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
c0c23a60
RK
26The protocol is liable to change without notice.
27You are recommended to check the implementation before believing this document.
460b9539 28.SH "GENERAL SYNTAX"
c0c23a60
RK
29Everything is encoded using UTF-8.
30See
f9635e06
RK
31.B "CHARACTER ENCODING"
32below for more detail on character encoding issues.
460b9539 33.PP
f9635e06
RK
34Commands and responses consist of a line perhaps followed (depending on the
35command or response) by a body.
460b9539 36.PP
37The line syntax is the same as described in \fBdisorder_config\fR(5) except
38that comments are prohibited.
39.PP
40Bodies borrow their syntax from RFC821; they consist of zero or more ordinary
41lines, with any initial full stop doubled up, and are terminated by a line
42consisting of a full stop and a line feed.
43.SH COMMANDS
44Commands always have a command name as the first field of the line; responses
c0c23a60
RK
45always have a 3-digit response code as the first field.
46See below for more details about this field.
460b9539 47.PP
48All commands require the connection to have been already authenticated unless
c0c23a60
RK
49stated otherwise.
50If not stated otherwise, the \fBread\fR right is sufficient to execute
51the command.
460b9539 52.PP
53Neither commands nor responses have a body unless stated otherwise.
54.TP
0f55e905 55.B adduser \fIUSERNAME PASSWORD \fR[\fIRIGHTS\fR]
c0c23a60
RK
56Create a new user with the given username and password.
57The new user's rights list can be specified; if it is not
58then the \fBdefault_rights\fR setting applies instead.
59Requires the \fBadmin\fR right, and only works on local
0f55e905 60connections.
eb5dc014 61.TP
460b9539 62.B allfiles \fIDIRECTORY\fR [\fIREGEXP\fR]
5818980a 63List all the files and directories in \fIDIRECTORY\fR in a response body.
460b9539 64If \fIREGEXP\fR is present only matching files and directories are returned.
65.TP
ba39faf6 66.B confirm \fICONFIRMATION
c0c23a60
RK
67Confirm user registration.
68\fICONFIRMATION\fR is as returned from \fBregister\fR below.
69This command can be used without logging in.
ba39faf6 70.TP
eb5dc014 71.B cookie \fICOOKIE
0d350ff0 72Log a user back in using a cookie created with \fBmake\-cookie\fR.
c0c23a60 73The response contains the username.
eb5dc014
RK
74.TP
75.B deluser \fIUSERNAME
c0c23a60
RK
76Delete the named user.
77Requires the \fBadmin\fR right, and only works on local connections.
460b9539 78.TP
79.B dirs \fIDIRECTORY\fR [\fIREGEXP\fR]
5818980a 80List all the directories in \fIDIRECTORY\fR in a response body.
460b9539 81If \fIREGEXP\fR is present only matching directories are returned.
82.TP
83.B disable \fR[\fBnow\fR]
c0c23a60
RK
84Disable further playing.
85If the optional \fBnow\fR argument is present then the current track
86is stopped.
87Requires the \fBglobal prefs\fR right.
eb5dc014
RK
88.TP
89.B edituser \fIUSERNAME PROPERTY VALUE
c0c23a60
RK
90Set a user property.
91With the \fBadmin\fR right any username and property may be specified.
92Otherwise the \fBuserinfo\fR right is required and only the
eb5dc014 93\fBemail\fR and \fBpassword\fR properties may be set.
0517868c
RK
94.IP
95User properties are syntax-checked before setting. For instance \fBemail\fR
96must contain an "@" sign or you will get an error. (Setting an empty value for
97\fBemail\fR is allowed and removes the property.)
460b9539 98.TP
99.B enable
c0c23a60
RK
100Re-enable further playing, and is the opposite of \fBdisable\fR.
101Requires the \fBglobal prefs\fR right.
460b9539 102.TP
103.B enabled
c0c23a60
RK
104Report whether playing is enabled.
105The second field of the response line will be \fByes\fR or \fBno\fR.
460b9539 106.TP
107.B exists \fITRACK\fR
c0c23a60
RK
108Report whether the named track exists.
109The second field of the response line will be \fByes\fR or \fBno\fR.
460b9539 110.TP
111.B files \fIDIRECTORY\fR [\fIREGEXP\fR]
5818980a 112List all the files in \fIDIRECTORY\fR in a response body.
460b9539 113If \fIREGEXP\fR is present only matching files are returned.
114.TP
115.B get \fITRACK\fR \fIPREF\fR
c0c23a60
RK
116Getsa preference value.
117On success the second field of the response line will have the value.
fb1bc1f5
RK
118.IP
119If the track or preference do not exist then the response code is 555.
460b9539 120.TP
0d350ff0 121.B get\-global \fIKEY\fR
460b9539 122Get a global preference.
fb1bc1f5
RK
123.IP
124If the preference does not exist then the response code is 555.
460b9539 125.TP
126.B length \fITRACK\fR
c0c23a60
RK
127Get the length of the track in seconds.
128On success the second field of the response line will have the value.
460b9539 129.TP
130.B log
c0c23a60
RK
131Send event log messages in a response body.
132The command will never terminate.
133Any further data sent to the server will be discarded (explicitly;
134i.e. it will not accumulate in a buffer somewhere).
460b9539 135.IP
136See \fBEVENT LOG\fR below for more details.
137.TP
0d350ff0 138.B make\-cookie
eb5dc014
RK
139Returns an opaque string that can be used by the \fBcookie\fR command to log
140this user back in on another connection (until the cookie expires).
141.TP
460b9539 142.B move \fITRACK\fR \fIDELTA\fR
c0c23a60
RK
143Move a track in the queue.
144The track may be identified by ID (preferred) or name (which might cause
145confusion if it's there twice).
146\fIDELTA\fR should be an negative or positive integer and indicates how
147many steps towards the head of the queue the track should be moved.
eb5dc014
RK
148.IP
149Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
150depending on how the track came to be added to the queue.
460b9539 151.TP
152.B moveafter \fITARGET\fR \fIID\fR ...
c0c23a60
RK
153Move all the tracks in the \fIID\fR list after ID \fITARGET\fR.
154If \fITARGET\fR is the empty string then the listed tracks are put
155at the head of the queue.
156If \fITARGET\fR is listed in the ID list then the tracks are moved
460b9539 157to just after the first non-listed track before it, or to the head if there is
158no such track.
eb5dc014
RK
159.IP
160Requires one of the \fBmove mine\fR, \fBmove random\fR or \fBmove any\fR rights
161depending on how the tracks came to be added to the queue.
460b9539 162.TP
2a10b70b 163.B new \fR[\fIMAX\fR]
c0c23a60
RK
164Send the most recently added \fIMAX\fR tracks in a response body.
165If the argument is ommitted, the \fBnew_max\fR most recent tracks are
166listed (see \fBdisorder_config\fR(5)).
2a10b70b 167.TP
7858930d 168.B nop
c0c23a60
RK
169Do nothing.
170Used by
7858930d 171.BR disobedience (1)
c0c23a60
RK
172as a keepalive measure.
173This command does not require authentication.
7858930d 174.TP
460b9539 175.B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
c0c23a60
RK
176Get a track name part.
177Returns an empty string if a name part cannot be constructed.
460b9539 178.IP
179.I CONTEXT
180is one of
181.B sort
182or
183.B display
184and
185.I PART
186is usually one of
187.BR artist ,
188.B album
189or
190.BR title .
191.TP
192.B pause
c0c23a60
RK
193Pause the current track.
194Requires the \fBpause\fR right.
460b9539 195.TP
196.B play \fITRACK\fR
c0c23a60
RK
197Add a track to the queue.
198The response contains the queue ID of the track.
eb5dc014 199Requires the \fBplay\fR right.
460b9539 200.TP
201.B playing
5818980a 202Report what track is playing.
460b9539 203.IP
204If the response is \fB252\fR then the rest of the response line consists of
205track information (see below).
206.IP
207If the response is \fB259\fR then nothing is playing.
208.TP
209.B prefs \fBTRACK\fR
5818980a 210Send back the preferences for \fITRACK\fR in a response body.
460b9539 211Each line of the response has the usual line syntax, the first field being the
212name of the pref and the second the value.
213.TP
214.B queue
5818980a 215Send back the current queue in a response body, one track to a line, the track
c0c23a60
RK
216at the head of the queue (i.e. next to be be played) first.
217See below for the track information syntax.
460b9539 218.TP
0d350ff0 219.B random\-disable
c0c23a60
RK
220Disable random play (but don't stop the current track).
221Requires the \fBglobal prefs\fR right.
460b9539 222.TP
0d350ff0 223.B random\-enable
c0c23a60
RK
224Enable random play.
225Requires the \fBglobal prefs\fR right.
460b9539 226.TP
0d350ff0 227.B random\-enabled
c0c23a60
RK
228Report whether random play is enabled.
229The second field of the response line will be \fByes\fR or \fBno\fR.
460b9539 230.TP
231.B recent
5818980a 232Send back the current recently-played list in a response body, one track to a
c0c23a60
RK
233line, the track most recently played last.
234See below for the track information syntax.
460b9539 235.TP
236.B reconfigure
c0c23a60
RK
237Request that DisOrder reconfigure itself.
238Requires the \fBadmin\fR right.
460b9539 239.TP
90ad6c6e 240.B register \fIUSERNAME PASSWORD EMAIL
c0c23a60
RK
241Register a new user.
242Requires the \fBregister\fR right.
243The result contains a confirmation string; the user will be be able
244to log in until this has been presented back to the server via the
245\fBconfirm\fR command.
ba39faf6 246.TP
90ad6c6e
RK
247.B reminder \fIUSERNAME\fR
248Send a password reminder to user \fIUSERNAME\fR.
c0c23a60
RK
249If the user has no valid email address, or no password, or a
250reminder has been sent too recently, then no reminder will be sent.
6207d2f3 251.TP
460b9539 252.B remove \fIID\fR
c0c23a60
RK
253Remove the track identified by \fIID\fR.
254Requires one of the \fBremove mine\fR, \fBremove random\fR or
255\fBremove any\fR rights depending on how the
eb5dc014 256track came to be added to the queue.
460b9539 257.TP
dd9af5cb 258.B rescan \fR[\fBwait\fR] \fR[\fBfresh\fR]
c0c23a60
RK
259Rescan all roots for new or obsolete tracks.
260Requires the \fBrescan\fR right.
dd9af5cb
RK
261.IP
262If the \fBwait\fR flag is present then the response is delayed until the rescan
263completes.
264Otherwise the response arrives immediately.
265This is primarily intended for testing.
266.IP
267If the \fBfresh\fR flag is present a rescan is already underway then a second
268rescan will be started when it completes.
269The default behavior is to piggyback on the existing rescan.
270.IP
271NB that \fBfresh\fR is currently disabled in the server source, so using this
272flag will just provoke an error.
460b9539 273.TP
274.B resolve \fITRACK\fR
275Resolve a track name, i.e. if this is an alias then return the real track name.
276.TP
277.B resume
c0c23a60
RK
278Resume the current track after a \fBpause\fR command.
279Requires the \fBpause\fR right.
eb5dc014
RK
280.TP
281.B revoke \fBcookie\fR
0d350ff0 282Revoke a cookie previously created with \fBmake\-cookie\fR.
c0c23a60 283It will not be possible to use this cookie in the future.
460b9539 284.TP
0d350ff0 285.B rtp\-address
5818980a 286Report the RTP broadcast (or multicast) address, in the form \fIADDRESS
c0c23a60
RK
287PORT\fR.
288This command does not require authentication.
ca831831 289.TP
460b9539 290.B scratch \fR[\fIID\fR]
291Remove the track identified by \fIID\fR, or the currently playing track if no
c0c23a60
RK
292\fIID\fR is specified.
293Requires one of the \fBscratch mine\fR, \fBscratch random\fR or
294\fBscratch any\fR rights depending on how the track came to be
eb5dc014 295added to the queue.
460b9539 296.TP
2b33c4cf
RK
297.B schedule-add \fIWHEN\fR \fIPRIORITY\fR \fIACTION\fR ...
298Schedule an event for the future.
299.IP
300.I WHEN
301is the time when it should happen, as \fBtime_t\fR value.
302It must refer to a time in the future.
303.IP
304.I PRIORITY
305is the event priority.
306This can be \fBnormal\fR, in which case the event will be run at startup if its
307time has past, or \fBjunk\fR in which case it will be discarded if it is found
308to be in the past at startup.
309The meaning of other values is not defined.
310.IP
311.I ACTION
312is the action to perform.
313The choice of action determines the meaning of the remaining arguments.
314Possible actions are:
315.RS
316.TP
317.B play
318Play a track.
319The next argument is the track name.
320Requires the \fBplay\fR right.
321.TP
322.B set-global
323Set a global preference.
324The next argument is the preference name and the final argument is the value to
325set it to (omit it to unset it).
326Requires the \fBglobal prefs\fR right.
327.RE
328.IP
329You need the right at the point you create the event.
330It is not possible to create scheduled events in expectation of a future change
331in rights.
332.TP
333.B schedule-del \fIEVENT\fR
334Deletes a scheduled event.
335Users can always delete their own scheduled events; with the \fBadmin\fR
336right you can delete any event.
337.TP
338.B schedule-get \fIEVENT\fR
339Sends the details of scheduled event \fIEVENT\fR in a response body.
340Each line is a pair of strings quoted in the usual way, the first being the key
341ane the second the value.
342No particular order is used.
343.IP
344Scheduled events are considered public information.
345Right \fBread\fR is sufficient to see details of all events.
346.TP
347.B schedule-list
348Sends the event IDs of all scheduled events in a response body, in no
349particular order.
350Use \fBschedule-get\fR to get the details of each event.
351.TP
460b9539 352.B search \fITERMS\fR
c0c23a60
RK
353Search for tracks matching the search terms.
354The results are put in a response body, one to a line.
460b9539 355.IP
356The search string is split in the usual way, with quoting supported, into a
c0c23a60
RK
357list of terms.
358Only tracks matching all terms are included in the results.
460b9539 359.IP
360Any terms of the form \fBtag:\fITAG\fR limits the search to tracks with that
361tag.
362.IP
363All other terms are interpreted as individual words which must be present in
364the track name.
365.IP
366Spaces in terms don't currently make sense, but may one day be interpreted to
367allow searching for phrases.
368.TP
369.B \fBset\fR \fITRACK\fR \fIPREF\fR \fIVALUE\fR
c0c23a60
RK
370Set a preference.
371Requires the \fBprefs\fR right.
460b9539 372.TP
0d350ff0 373.B set\-global \fIKEY\fR \fIVALUE\fR
c0c23a60
RK
374Set a global preference.
375Requires the \fBglobal prefs\fR right.
460b9539 376.TP
377.B stats
378Send server statistics in plain text in a response body.
379.TP
380.B \fBtags\fR
381Send the list of currently known tags in a response body.
382.TP
383.B \fBunset\fR \fITRACK\fR \fIPREF\fR
c0c23a60
RK
384Unset a preference.
385Requires the \fBprefs\fR right.
460b9539 386.TP
0d350ff0 387.B \fBunset\-global\fR \fIKEY\fR
c0c23a60
RK
388Unset a global preference.
389Requires the \fBglobal prefs\fR right.
460b9539 390.TP
90ad6c6e
RK
391.B user \fIUSERNAME\fR \fIRESPONSE\fR
392Authenticate as user \fIUSERNAME\fR.
c0c23a60 393See
5e3f9e08
RK
394.B AUTHENTICATION
395below.
460b9539 396.TP
90ad6c6e 397.B userinfo \fIUSERNAME PROPERTY
3e3566ad
RK
398Get a user property.
399.TP
eb5dc014 400.B users
5818980a 401Send the list of currently known users in a response body.
eb5dc014 402.TP
460b9539 403.B version
404Send back a response with the server version as the second field.
405.TP
406.B volume \fR[\fILEFT\fR [\fIRIGHT\fR]]
407Get or set the volume.
408.IP
409With zero parameters just gets the volume and reports the left and right sides
410as the 2nd and 3rd fields of the response.
411.IP
c0c23a60
RK
412With one parameter sets both sides to the same value.
413With two parameters sets each side independently.
414Setting the volume requires the \fBvolume\fR right.
460b9539 415.SH RESPONSES
c0c23a60
RK
416Responses are three-digit codes.
417The first digit distinguishes errors from succesful responses:
460b9539 418.TP
419.B 2
420Operation succeeded.
421.TP
422.B 5
423Operation failed.
424.PP
425The second digit breaks down the origin of the response:
426.TP
427.B 0
c0c23a60
RK
428Generic responses not specific to the handling of the command.
429Mostly this is parse errors.
460b9539 430.TP
b4a80f69 431.B 1
43251x errors indicate that the user had insufficient rights for the command.
433.TP
460b9539 434.B 3
435Authentication responses.
436.TP
437.B 5
438Responses specific to the handling of the command.
439.PP
440The third digit provides extra information about the response:
441.TP
442.B 0
443Text part is just commentary.
444.TP
445.B 1
446Text part is a constant result e.g. \fBversion\fR.
447.TP
448.B 2
449Text part is a potentially variable result.
450.TP
451.B 3
452Text part is just commentary; a dot-stuffed body follows.
453.TP
454.B 4
c0c23a60
RK
455Text part is just commentary; an indefinite dot-stuffed body follows.
456(Used for \fBlog\fR.)
460b9539 457.TP
fb1bc1f5 458.B 5
c0c23a60
RK
459Used with "normal" errors, for instance a preference not being found.
460The text part is commentary.
fb1bc1f5 461.TP
460b9539 462.B 9
463The text part is just commentary (but would normally be a response for this
464command) e.g. \fBplaying\fR.
7b32e917
RK
465.PP
466Result strings (not bodies) intended for machine parsing (i.e. xx1 and xx2
467responses) are quoted.
460b9539 468.SH AUTHENTICATION
5e3f9e08 469When a connection is made the server sends a \fB231\fR response before any
c0c23a60
RK
470command is received.
471This contains a protocol generation, an algorithm name and a
472challenge encoded in hex, all separated by whitespace.
7b32e917
RK
473.PP
474The current protocol generation is \fB2\fR.
5e3f9e08 475.PP
b3141726 476The possible algorithms are (currently) \fBsha1\fR, \fBsha256\fR, \fBsha384\fR
c0c23a60
RK
477and \fBsha512\fR.
478\fBSHA1\fR etc work as synonyms.
460b9539 479.PP
5e3f9e08
RK
480The \fBuser\fR response consists of the selected hash of the user's password
481concatenated with the challenge, encoded in hex.
460b9539 482.SH "TRACK INFORMATION"
483Track information is encoded in a line (i.e. using the usual line syntax) as
c0c23a60
RK
484pairs of fields.
485The first is a name, the second a value.
486The names have the following meanings:
460b9539 487.TP 12
488.B expected
489The time the track is expected to be played at.
490.TP
491.B id
492A string uniquely identifying this queue entry.
493.TP
494.B played
495The time the track was played at.
496.TP
497.B scratched
498The user that scratched the track.
499.TP
500.B state
c0c23a60
RK
501The current track state.
502Valid states are:
460b9539 503.RS
504.TP 12
505.B failed
506The player failed (exited with nonzero status but wasn't scratched).
507.TP
508.B isscratch
509The track is actually a scratch.
510.TP
511.B no_player
512No player could be found for the track.
513.TP
514.B ok
515The track was played without any problems.
516.TP
517.B scratched
518The track was scratched.
519.TP
520.B started
521The track is currently playing.
522.TP
523.B unplayed
524In the queue, hasn't been played yet.
525.TP
526.B quitting
527The track was terminated because the server is shutting down.
528.RE
529.TP
530.B submitter
531The user that submitted the track.
532.TP
533.B track
534The filename of the track.
535.TP
536.B when
537The time the track was added to the queue.
538.TP
539.B wstat
540The wait status of the player in decimal.
541.SH NOTES
542Times are decimal integers using the server's \fBtime_t\fR.
543.PP
544For file listings, the regexp applies to the basename of the returned file, not
c0c23a60
RK
545the whole filename, and letter case is ignored.
546\fBpcrepattern\fR(3) describes the regexp syntax.
460b9539 547.PP
548Filenames are in UTF-8 even if the collection they come from uses some other
549encoding - if you want to access the real file (in such cases as the filenames
550actually correspond to a real file) you'll have to convert to whatever the
551right encoding is.
552.SH "EVENT LOG"
553The event log consists of lines starting with a hexadecimal timestamp and a
c0c23a60
RK
554keyword followed by (optionally) parameters.
555The parameters are quoted in the usual DisOrder way.
556Currently the following keywords are used:
460b9539 557.TP
558.B completed \fITRACK\fR
559Completed playing \fITRACK\fR
560.TP
561.B failed \fITRACK\fR \fIERROR\fR
562Completed playing \fITRACK\fR with an error status
563.TP
90ad6c6e
RK
564.B moved \fIUSERNAME\fR
565User \fIUSERNAME\fR moved some track(s).
c0c23a60 566Further details aren't included any more.
460b9539 567.TP
90ad6c6e 568.B playing \fITRACK\fR [\fIUSERNAME\fR]
460b9539 569Started playing \fITRACK\fR.
570.TP
571.B queue \fIQUEUE-ENTRY\fR...
572Added \fITRACK\fR to the queue.
573.TP
574.B recent_added \fIQUEUE-ENTRY\fR...
575Added \fIID\fR to the recently played list.
576.TP
577.B recent_removed \fIID\fR
578Removed \fIID\fR from the recently played list.
579.TP
90ad6c6e 580.B removed \fIID\fR [\fIUSERNAME\fR]
c0c23a60 581Queue entry \fIID\fR was removed.
90ad6c6e 582This is used both for explicit removal (when \fIUSERNAME\fR is present)
c0c23a60 583and when playing a track (when it is absent).
460b9539 584.TP
e025abff
RK
585.B rescanned
586A rescan completed.
587.TP
90ad6c6e
RK
588.B scratched \fITRACK\fR \fIUSERNAME\fR
589\fITRACK\fR was scratched by \fIUSERNAME\fR.
460b9539 590.TP
591.B state \fIKEYWORD\fR
c0c23a60
RK
592Some state change occurred.
593The current set of keywords is:
460b9539 594.RS
595.TP
5abe307a
RK
596.B completed
597The current track completed successfully.
598.TP
460b9539 599.B disable_play
600Playing was disabled.
601.TP
602.B disable_random
603Random play was disabled.
604.TP
605.B enable_play
606Playing was enabled.
607.TP
608.B enable_random
609Random play was enabled.
610.TP
5abe307a
RK
611.B failed
612The current track failed.
613.TP
460b9539 614.B pause
615The current track was paused.
616.TP
5abe307a
RK
617.B playing
618A track started playing.
619.TP
460b9539 620.B resume
621The current track was resumed.
5abe307a 622.TP
ad492e00
RK
623.B rights-changed \fIRIGHTS\fR
624User's rights were changed.
625.TP
5abe307a
RK
626.B scratched
627The current track was scratched.
628.PP
629To simplify client implementation, \fBstate\fR commands reflecting the current
630state are sent at the start of the log.
460b9539 631.RE
58d2aad2
RK
632.TB
633.B user-add \fIUSERNAME\fR
634A user was created.
635.TP
636.B user-delete \fIUSERNAME\fR
637A user was deleted.
638.TP
639.B user-edit \fIUSERNAME\fR \fIPROPERTY\fR
640Some property of a user was edited.
641.TP
642.B user-confirm \fIUSERNAME\fR
643A user's login was confirmed (via the web interface).
460b9539 644.TP
645.B volume \fILEFT\fR \fIRIGHT\fR
646The volume changed.
647.PP
648.IR QUEUE-ENTRY ...
649is as defined in
650.B "TRACK INFORMATION"
651above.
58d2aad2
RK
652.PP
653The \fBuser-*\fR messages are only sent to admin users, and are not sent over
654non-local connections unless \fBremote_userman\fR is enabled.
f9635e06 655.SH "CHARACTER ENCODING"
c0c23a60
RK
656All data sent by both server and client is encoded using UTF-8.
657Moreover it must be valid UTF-8, i.e. non-minimal sequences are not
658permitted, nor are surrogates, nor are code points outside the
659Unicode code space.
f9635e06
RK
660.PP
661There are no particular normalization requirements on either side of the
c0c23a60
RK
662protocol.
663The server currently converts internally to NFC, the client must
f9635e06
RK
664normalize the responses returned if it needs some normalized form for further
665processing.
666.PP
667The various characters which divide up lines may not be followed by combining
c0c23a60
RK
668characters.
669For instance all of the following are prohibited:
f9635e06
RK
670.TP
671.B o
c0c23a60
RK
672LINE FEED followed by a combining character.
673For example the sequence LINE FEED, COMBINING GRAVE ACCENT is never permitted.
f9635e06
RK
674.TP
675.B o
676APOSTROPHE or QUOTATION MARK followed by a combining character when used to
c0c23a60
RK
677delimit fields.
678For instance a line starting APOSTROPHE, COMBINING CEDILLA is prohibited.
f9635e06
RK
679.IP
680Note that such sequences are not prohibited when the quote character cannot be
c0c23a60
RK
681interpreted as a field delimiter.
682For instance APOSTROPHE, REVERSE SOLIDUS, APOSTROPHE, COMBINING CEDILLA,
683APOSTROPHE would be permitted.
f9635e06
RK
684.TP
685.B o
686REVERSE SOLIDUS (BACKSLASH) followed by a combining character in a quoted
c0c23a60
RK
687string when it is the first character of an escape sequence.
688For instance a line starting APOSTROPHE, REVERSE SOLIDUS, COMBINING TILDE
689is prohibited.
f9635e06
RK
690.IP
691As above such sequences are not prohibited when the character is not being used
c0c23a60
RK
692to start an escape sequence.
693For instance APOSTROPHE, REVERSE SOLIDUS, REVERSE SOLIDS, COMBINING TILDE,
694APOSTROPHE is permitted.
f9635e06
RK
695.TP
696.B o
697Any of the field-splitting whitespace characters followed by a combining
c0c23a60
RK
698character when not part of a quoted field.
699For instance a line starting COLON, SPACE, COMBINING CANDRABINDU is prohibited.
f9635e06
RK
700.IP
701As above non-delimiter uses are fine.
702.TP
703.B o
704The FULL STOP characters used to quote or delimit a body.
705.PP
706Furthermore none of these characters are permitted to appear in the context of
707a canonical decomposition (i.e. they must still be present when converted to
c0c23a60
RK
708NFC).
709In practice however this is not an issue in Unicode 5.0.
f9635e06
RK
710.PP
711These rules are consistent with the observation that the split() function is
c0c23a60
RK
712essentially a naive ASCII parser.
713The implication is not that these sequences never actually appear in
714the protocol, merely that the server is not required to honor them in
715any useful way nor be consistent between versions: in current
f9635e06
RK
716versions the result will be lines and fields that start with combining
717characters and are not necessarily split where you expect, but future versions
718may remove them, reject them or ignore some or all of the delimiters that have
719following combining characters, and no notice will be given of any change.
460b9539 720.SH "SEE ALSO"
721\fBdisorder\fR(1),
722\fBtime\fR(2),
723\fBdisorder\fR(3),
724\fBpcrepattern\fR(3)
725\fBdisorder_config\fR(5),
726\fBdisorderd\fR(8),
727\fButf8\fR(7)
728.\" Local Variables:
729.\" mode:nroff
730.\" fill-column:79
731.\" End: