chiark / gitweb /
build depends compatible with squeeze
[disorder] / doc / disorder.3
CommitLineData
460b9539 1.\"
5aff007d 2.\" Copyright (C) 2004-2008 Richard Kettlewell
460b9539 3.\"
e7eb3a27 4.\" This program is free software: you can redistribute it and/or modify
460b9539 5.\" it under the terms of the GNU General Public License as published by
e7eb3a27 6.\" the Free Software Foundation, either version 3 of the License, or
460b9539 7.\" (at your option) any later version.
e7eb3a27
RK
8.\"
9.\" This program is distributed in the hope that it will be useful,
10.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12.\" GNU General Public License for more details.
13.\"
460b9539 14.\" You should have received a copy of the GNU General Public License
e7eb3a27 15.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
460b9539 16.\"
17.TH disorder 3
18.SH NAME
19disorder \- plugin interface to DisOrder jukebox
20.SH SYNOPSIS
21.B "#include <disorder.h>"
22.SH DESCRIPTION
23This header file defines the plugin interface to DisOrder.
24.PP
25The first half of this man page describes the functions DisOrder
26provides to plugins; the second half describes the functions that
27plugins must provide.
28.SH "MEMORY ALLOCATION"
c0c23a60
RK
29DisOrder uses a garbage collector internally.
30Therefore it is recommended that plugins use the provided memory
31allocation interface, rather than calling \fBmalloc\fR(3) etc directly.
460b9539 32.PP
33.nf
34\fBvoid *disorder_malloc(size_t);
35void *disorder_realloc(void *, size_t);
36.fi
37.IP
38These functions behave much like \fBmalloc\fR(3) and \fBrealloc\fR(3)
39except that they never fail; they always zero out the memory
40allocated; and you do not need to free the result.
41.IP
42They may still return a null pointer if asked for a 0-sized
43allocation.
44.PP
45.nf
46\fBvoid *disorder_malloc_noptr(size_t);
47void *disorder_realloc_noptr(void *, size_t);
48.fi
49.IP
50These functions are like \fBmalloc\fR(3) and \fBrealloc\fR(3)
51except that they never fail and you must not put any pointer
52values in the allocated memory.
53.IP
54They may still return a null pointer if asked for a 0-sized
c0c23a60
RK
55allocation.
56They do not guarantee to zero out the memory allocated.
460b9539 57.PP
58.nf
59\fBchar *disorder_strdup(const char *);
60char *disorder_strndup(const char *, size_t);
61.fi
62.IP
63These functions are like \fBstrdup\fR(3) and \fBstrndup\fR(3) except
64that they never fail and you do not need to free the result.
65.PP
66.nf
67\fBint disorder_asprintf(char **rp, const char *fmt, ...);
68int disorder_snprintf(char buffer[], size_t bufsize,
69 const char *fmt, ...);
70.fi
71.IP
72These function are like \fBsnprintf\fR(3) and \fBasprintf\fR(3).
73.B disorder_asprintf
74never fails on memory allocation and
75you do not need to free the results.
76.IP
77Floating point conversions and wide character support are not
78currently implemented.
b6579a61
RK
79.IP
80These functions will cope with UTF-8 even if the current locale uses
81some other encoding.
460b9539 82.PP
83"Never fail" in the above means that the process is terminated on error.
84.SH LOGGING
85Standard error doesn't reliably go anywhere in current versions of DisOrder,
86and whether syslog is to be used varies depending on how the program is
c0c23a60
RK
87invoked.
88Therefore plugins should use these functions to log any errors or
460b9539 89informational messages.
90.PP
91.nf
92\fBvoid disorder_error(int errno_value, const char *fmt, ...);
93.fi
94.IP
c0c23a60
RK
95Log an error message.
96If \fBerrno_value\fR is not 0 then the relevant
460b9539 97string is included in the error message.
98.PP
99.nf
100\fBvoid disorder_fatal(int errno_value, const char *fmt, ...);
101.fi
102.IP
c0c23a60
RK
103Log an error message and then terminate the process.
104If \fBerrno_value\fR is not 0 then the relevant string is included in the
460b9539 105error message.
106.IP
107.B disorder_fatal
108is the right way to terminate the process if a fatal error arises.
109You shouldn't usually try to use \fBexit\fR(3) or \fB_exit\fR(2).
110.PP
111.nf
112\fBvoid disorder_info(const char *fmt, ...);
113.fi
114.IP
115Log a message.
116.IP
117.SH "TRACK DATABASE"
118The functions in this section provide a way of accessing the track database.
119In server plugins these access the database directly; in client plugins the
120requests are transmitted to the server over a socket.
121.PP
122All strings in this section are encoded using UTF-8.
123.PP
124.nf
125\fBint disorder_track_exists(const char *track);
126.fi
127.IP
128This function returns non-0 if \fBtrack\fR exists and 0 if it does
129not.
130.PP
131.nf
132\fBconst char *disorder_track_get_data(const char *track,
133 const char *key);
134.fi
135.IP
136This function looks up the value of \fBkey\fR for \fBtrack\fR and
c0c23a60
RK
137returns a pointer to a copy of it.
138Do not bother to free the pointer.
460b9539 139If the track or key are not found a null pointer is returned.
140.PP
141.nf
142\fBint disorder_track_set_data(const char *track,
143 const char *key,
144 const char *value);
145.fi
146.IP
147This function sets the value of \fBkey\fR for \fBtrack\fR to
c0c23a60 148\fBvalue\fR.
3db7469f 149On success, 0 is returned; on error, \-1 is returned.
460b9539 150.IP
151If \fBvalue\fR is a null pointer then the preference is deleted.
152.IP
153Values starting with an underscore are stored in the tracks database,
154and are lost if the track is deleted; they should only ever have
c0c23a60
RK
155values that can be regenerated on demand.
156Other values are stored in the prefs database and never get
157automatically deleted.
460b9539 158.SH "PLUGIN FUNCTIONS"
159This section describes the functions that you must implement to write various
c0c23a60
RK
160plugins.
161All of the plugins have at least one standard implementation available
162in the DisOrder source.
460b9539 163.PP
164Some functions are listed as only available in server plugins.
165Currently this means that they are not even defined outside the
166server.
167.PP
168All strings in this section are encoded using UTF-8.
b6579a61
RK
169.SS "Tracklength Plugins"
170These are server plugins defined by the \fBtracklength\fR directive.
460b9539 171.PP
172.nf
173\fBlong disorder_tracklength(const char *track,
174 const char *path);
175.fi
176.IP
c0c23a60
RK
177Called to calculate the length of a track.
178\fBtrack\fR is the track name (UTF-8) and \fBpath\fR is the path
179name if there was one, or a null pointer otherwise.
180\fBpath\fR will be the same byte string return from
460b9539 181the scanner plugin, and so presumably encoded according to the
182filesystem encoding.
183.IP
b6579a61
RK
184To clarify this point, if the track must be opened to compute its
185length, you would normally use \fBpath\fR and not \fBtrack\fR.
186.IP
460b9539 187If the return value is positive it should be the track length in
188seconds (round up if it is not an integral number of seconds long).
189.IP
190If the return value is zero then the track length is unknown.
191.IP
192If the return value is negative then an error occurred determining the
193track length.
194.PP
195Tracklength plugins are invoked from a subprocess of the server, so
196they can block without disturbing the server's operation.
197.SS notify.so
198This is a server plugin.
199.PP
200.nf
201\fBvoid disorder_notify_play(const char *track,
202 const char *submitter);
203.fi
204.IP
c0c23a60
RK
205Called when \fBtrack\fR is about to be played.
206\fBsubmitter\fR identifies the submitter or is a null pointer if
207the track was picked for random play.
460b9539 208.PP
209.nf
210\fBvoid disorder_notify_scratch(const char *track,
211 const char *submitter,
212 const char *scratcher,
213 int seconds);
214.fi
215.IP
c0c23a60
RK
216Called when \fBtrack\fR is scratched by \fBscratcher\fR.
217\fBsubmitter\fR identifies the submitter or is a null pointer if
218the track was picked for random play.
219\fBseconds\fR is the number of seconds since the track started playing.
460b9539 220.PP
221.nf
222\fBvoid disorder_notify_not_scratched(const char *track,
223 const char *submitter);
224.fi
225.IP
226Called when \fBtrack\fR completes without being scratched (an error might have
c0c23a60
RK
227occurred though).
228\fBsubmitter\fR identifies the submitter or is a null pointer if the
229track was picked for random play.
460b9539 230.PP
231.nf
232\fBvoid disorder_notify_queue(const char *track,
233 const char *submitter);
234.fi
235.IP
236Called when \fBtrack\fR is added to the queue by \fBsubmitter\fR
c0c23a60
RK
237(which is never a null pointer).
238Not called for scratches.
460b9539 239.PP
240.nf
241\fBvoid disorder_notify_queue_remove(const char *track,
242 const char *remover);
243.fi
244.IP
245Called when \fBtrack\fR is removed from queue by \fBremover\fR (which
246is never a null pointer).
247.PP
248.nf
249\fBvoid disorder_notify_queue_move(const char *track,
250 const char *remover);
251.fi
252.IP
253Called when \fBtrack\fR is moved in the queue by \fBmover\fR
254(which is never a null pointer).
255.PP
256.nf
257\fBvoid disorder_notify_pause(const char *track,
258 const char *who);
259.fi
260.IP
261Called when \fBtrack\fR is paused by \fBwho\fR
262(which might be a null pointer).
263.PP
264.nf
265\fBvoid disorder_notify_resume(const char *track,
266 const char *who);
267.fi
268.IP
269Called when \fBtrack\fR is resumed by \fBwho\fR
270(which might be a null pointer).
271.SS "Scanner Plugins"
272Scanner plugins are server plugins and may have any name; they are
273chosen via the configuration file.
274.PP
275.nf
276\fBvoid disorder_scan(const char *root);
277.fi
278.IP
c0c23a60
RK
279Write a list of files below \fBroot\fR to standard output.
280Each filename should be in the encoding defined for this root in the
460b9539 281configuration file and should be terminated by character 0.
282.IP
283It is up to the plugin implementor whether they prefer to use stdio or
284write to file descriptor 1 directly.
285.IP
286All the filenames had better start with \fBroot\fR as this is used to
287match them back up to the right collection to call
288\fBdisorder_check\fR on.
289.PP
290.nf
291\fBint disorder_check(const char *root, const char *path);
292.fi
293.IP
c0c23a60 294Check whether file \fBpath\fR under \fBroot\fR still exists.
3db7469f 295Should return 1 if it exists, 0 if it does not and \-1 on error.
c0c23a60 296This is run in the main server process.
460b9539 297.PP
298Both scan and recheck are executed inside a subprocess, so it will not
299break the server if they block for an extended period (though of
300course, they should not gratuitously take longer than necessary to do
301their jobs).
302.SS "Player plugins"
303Player plugins are server plugins and may have any name; they are
304chosen via the configuration file.
305.PP
306.nf
307extern const unsigned long disorder_player_type;
308.fi
309.IP
c0c23a60
RK
310This defines the player type and capabilities.
311It should consist of a single type value ORed with any number of
312capability values.
313The following are known type values:
460b9539 314.RS
315.TP
316.B DISORDER_PLAYER_STANDALONE
317A standalone player that writes directly to some suitable audio
318device.
319.TP
320.B DISORDER_PLAYER_RAW
6a213ecb 321A player that writes raw samples to \fB$DISORDER_RAW_FD\fR.
460b9539 322.RE
323.IP
324Known capabilities are:
325.RS
326.TP
327.B DISORDER_PLAYER_PREFORK
328Supports the prefork and cleanup calls.
329.TP
330.B DISORDER_PLAYER_PAUSES
331Supports the pause and resume calls.
332.RE
333.PP
334.nf
335\fBvoid *disorder_play_prefork(const char *track);
336.fi
337.IP
338Called before a track is played, if \fB_PREFORK\fR is set.
c0c23a60
RK
339\fBtrack\fR is the name of the track in UTF-8.
340This function must never block, as it runs inside the main loop of the server.
460b9539 341.IP
342The return value will be passed to the functions below as \fBdata\fR.
343On error, a null pointer should be returned.
344.PP
345.nf
346\fBvoid disorder_play_cleanup(void *data);
347.fi
348.IP
349Called after a track has been completed, if \fB_PREFORK\fR is set, for
c0c23a60
RK
350instance to release the memory used by \fBdata\fR.
351This function must never block, as it runs inside the main loop of the server.
460b9539 352.PP
353.nf
354\fBvoid disorder_play_track(const char *const *parameters,
355 int nparameters,
356 const char *path,
357 const char *track,
358 void *data);
359.fi
360.IP
361Play a track.
362.IP
363\fBpath\fR is the path name as originally encoded in the filesystem.
364This is the value you should ultimately pass to \fBopen\fR(2).
365.IP
c0c23a60
RK
366\fBtrack\fR is the path name converted to UTF-8.
367This value (possibly converted to some other encoding) should be used
368in any logs, etc.
460b9539 369.IP
370If there is no meaningful path, or if the track is a scratch (where no
371filename encoding information is available), \fBpath\fR will be equal
372to \fBtrack\fR.
373.IP
374The parameters are any additional arguments
375supplied to the \fBplayer\fR configuration file command.
376.IP
377This function is always called inside a fork, and it should not return
378until playing has finished.
379.IP
380DisOrder sends the subprocess a signal if the track is to be scratched
c0c23a60
RK
381(and when \fBdisorderd\fR is shut down).
382By default this signal is \fBSIGKILL\fR but it can be reconfigured.
460b9539 383.PP
384.nf
385\fBint disorder_play_pause(long *playedp,
386 void *data);
387.fi
388.IP
c0c23a60
RK
389Pauses the current track, for players that support pausing.
390This function must never block, as it runs inside the main loop of the
460b9539 391server.
392.IP
393On success, should return 0 and set \fB*playedp\fR to the number of
3db7469f 394seconds played so far of this track, or to \-1 if this cannot be
460b9539 395determined.
396.IP
3db7469f 397On error, should return \-1.
460b9539 398.PP
399.nf
400\fBvoid disorder_play_resume(void *data);
401.fi
402.IP
c0c23a60
RK
403Resume playing the current track after a pause.
404This function must never block, as it runs inside the main loop of the server.
460b9539 405.SH NOTES
406There is no special DisOrder library to link against; the symbols are
c0c23a60 407exported by the executables themselves.
460b9539 408(You should NOT try to link against \fB-ldisorder\fR.)
409Plugins must be separately
410linked against any other libraries they require, even if the DisOrder
411executables are already linked against them.
412.PP
413The easiest approach is probably to develop the plugin inside the
c0c23a60
RK
414DisOrder tree; then you can just use DisOrder's build system.
415This might also make it easier to submit patches if you write something of
460b9539 416general utility.
417.PP
418Failing that you can use Libtool, if you make sure to pass the
c0c23a60
RK
419\fB-module\fR option.
420For current versions of DisOrder you only need the shared object
421itself, not the \fB.la\fR file.
460b9539 422.PP
423If you know the right runes for your toolchain you could also build
424the modules more directly.
425.PP
426It is possible, up to a point, to implement several plugin interfaces
c0c23a60
RK
427from within a single shared object.
428If you ever use any of the functions that are listed as only being
429available in server plugins, though, then you can only use the
430resulting shared object as a server plugin.
460b9539 431.SH "SEE ALSO"
432.BR disorderd (8),
433.BR disorder (1),
434.BR disorder_config (5)
435.\" Local Variables:
436.\" mode:nroff
437.\" End: