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