chiark / gitweb /
Build fixes for GCC 4.1
[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.SH "PLUGIN FUNCTIONS"
161This section describes the functions that you must implement to write various
c0c23a60
RK
162plugins.
163All of the plugins have at least one standard implementation available
164in the DisOrder source.
460b9539 165.PP
166Some functions are listed as only available in server plugins.
167Currently this means that they are not even defined outside the
168server.
169.PP
170All strings in this section are encoded using UTF-8.
b6579a61
RK
171.SS "Tracklength Plugins"
172These are server plugins defined by the \fBtracklength\fR directive.
460b9539 173.PP
174.nf
175\fBlong disorder_tracklength(const char *track,
176 const char *path);
177.fi
178.IP
c0c23a60
RK
179Called to calculate the length of a track.
180\fBtrack\fR is the track name (UTF-8) and \fBpath\fR is the path
181name if there was one, or a null pointer otherwise.
182\fBpath\fR will be the same byte string return from
460b9539 183the scanner plugin, and so presumably encoded according to the
184filesystem encoding.
185.IP
b6579a61
RK
186To clarify this point, if the track must be opened to compute its
187length, you would normally use \fBpath\fR and not \fBtrack\fR.
188.IP
460b9539 189If the return value is positive it should be the track length in
190seconds (round up if it is not an integral number of seconds long).
191.IP
192If the return value is zero then the track length is unknown.
193.IP
194If the return value is negative then an error occurred determining the
195track length.
196.PP
197Tracklength plugins are invoked from a subprocess of the server, so
198they can block without disturbing the server's operation.
199.SS notify.so
200This is a server plugin.
201.PP
202.nf
203\fBvoid disorder_notify_play(const char *track,
204 const char *submitter);
205.fi
206.IP
c0c23a60
RK
207Called when \fBtrack\fR is about to be played.
208\fBsubmitter\fR identifies the submitter or is a null pointer if
209the track was picked for random play.
460b9539 210.PP
211.nf
212\fBvoid disorder_notify_scratch(const char *track,
213 const char *submitter,
214 const char *scratcher,
215 int seconds);
216.fi
217.IP
c0c23a60
RK
218Called when \fBtrack\fR is scratched by \fBscratcher\fR.
219\fBsubmitter\fR identifies the submitter or is a null pointer if
220the track was picked for random play.
221\fBseconds\fR is the number of seconds since the track started playing.
460b9539 222.PP
223.nf
224\fBvoid disorder_notify_not_scratched(const char *track,
225 const char *submitter);
226.fi
227.IP
228Called when \fBtrack\fR completes without being scratched (an error might have
c0c23a60
RK
229occurred though).
230\fBsubmitter\fR identifies the submitter or is a null pointer if the
231track was picked for random play.
460b9539 232.PP
233.nf
234\fBvoid disorder_notify_queue(const char *track,
235 const char *submitter);
236.fi
237.IP
238Called when \fBtrack\fR is added to the queue by \fBsubmitter\fR
c0c23a60
RK
239(which is never a null pointer).
240Not called for scratches.
460b9539 241.PP
242.nf
243\fBvoid disorder_notify_queue_remove(const char *track,
244 const char *remover);
245.fi
246.IP
247Called when \fBtrack\fR is removed from queue by \fBremover\fR (which
248is never a null pointer).
249.PP
250.nf
251\fBvoid disorder_notify_queue_move(const char *track,
252 const char *remover);
253.fi
254.IP
255Called when \fBtrack\fR is moved in the queue by \fBmover\fR
256(which is never a null pointer).
257.PP
258.nf
259\fBvoid disorder_notify_pause(const char *track,
260 const char *who);
261.fi
262.IP
263Called when \fBtrack\fR is paused by \fBwho\fR
264(which might be a null pointer).
265.PP
266.nf
267\fBvoid disorder_notify_resume(const char *track,
268 const char *who);
269.fi
270.IP
271Called when \fBtrack\fR is resumed by \fBwho\fR
272(which might be a null pointer).
273.SS "Scanner Plugins"
274Scanner plugins are server plugins and may have any name; they are
275chosen via the configuration file.
276.PP
277.nf
278\fBvoid disorder_scan(const char *root);
279.fi
280.IP
c0c23a60
RK
281Write a list of files below \fBroot\fR to standard output.
282Each filename should be in the encoding defined for this root in the
460b9539 283configuration file and should be terminated by character 0.
284.IP
285It is up to the plugin implementor whether they prefer to use stdio or
286write to file descriptor 1 directly.
287.IP
288All the filenames had better start with \fBroot\fR as this is used to
289match them back up to the right collection to call
290\fBdisorder_check\fR on.
291.PP
292.nf
293\fBint disorder_check(const char *root, const char *path);
294.fi
295.IP
c0c23a60
RK
296Check whether file \fBpath\fR under \fBroot\fR still exists.
297Should return 1 if it exists, 0 if it does not and -1 on error.
298This is run in the main server process.
460b9539 299.PP
300Both scan and recheck are executed inside a subprocess, so it will not
301break the server if they block for an extended period (though of
302course, they should not gratuitously take longer than necessary to do
303their jobs).
304.SS "Player plugins"
305Player plugins are server plugins and may have any name; they are
306chosen via the configuration file.
307.PP
308.nf
309extern const unsigned long disorder_player_type;
310.fi
311.IP
c0c23a60
RK
312This defines the player type and capabilities.
313It should consist of a single type value ORed with any number of
314capability values.
315The following are known type values:
460b9539 316.RS
317.TP
318.B DISORDER_PLAYER_STANDALONE
319A standalone player that writes directly to some suitable audio
320device.
321.TP
322.B DISORDER_PLAYER_RAW
323A player that writes raw samples to \fB$DISORDER_RAW_FD\fR, for
324instance by using the \fBdisorder\fR libao driver.
325.RE
326.IP
327Known capabilities are:
328.RS
329.TP
330.B DISORDER_PLAYER_PREFORK
331Supports the prefork and cleanup calls.
332.TP
333.B DISORDER_PLAYER_PAUSES
334Supports the pause and resume calls.
335.RE
336.PP
337.nf
338\fBvoid *disorder_play_prefork(const char *track);
339.fi
340.IP
341Called before a track is played, if \fB_PREFORK\fR is set.
c0c23a60
RK
342\fBtrack\fR is the name of the track in UTF-8.
343This function must never block, as it runs inside the main loop of the server.
460b9539 344.IP
345The return value will be passed to the functions below as \fBdata\fR.
346On error, a null pointer should be returned.
347.PP
348.nf
349\fBvoid disorder_play_cleanup(void *data);
350.fi
351.IP
352Called after a track has been completed, if \fB_PREFORK\fR is set, for
c0c23a60
RK
353instance to release the memory used by \fBdata\fR.
354This function must never block, as it runs inside the main loop of the server.
460b9539 355.PP
356.nf
357\fBvoid disorder_play_track(const char *const *parameters,
358 int nparameters,
359 const char *path,
360 const char *track,
361 void *data);
362.fi
363.IP
364Play a track.
365.IP
366\fBpath\fR is the path name as originally encoded in the filesystem.
367This is the value you should ultimately pass to \fBopen\fR(2).
368.IP
c0c23a60
RK
369\fBtrack\fR is the path name converted to UTF-8.
370This value (possibly converted to some other encoding) should be used
371in any logs, etc.
460b9539 372.IP
373If there is no meaningful path, or if the track is a scratch (where no
374filename encoding information is available), \fBpath\fR will be equal
375to \fBtrack\fR.
376.IP
377The parameters are any additional arguments
378supplied to the \fBplayer\fR configuration file command.
379.IP
380This function is always called inside a fork, and it should not return
381until playing has finished.
382.IP
383DisOrder sends the subprocess a signal if the track is to be scratched
c0c23a60
RK
384(and when \fBdisorderd\fR is shut down).
385By default this signal is \fBSIGKILL\fR but it can be reconfigured.
460b9539 386.PP
387.nf
388\fBint disorder_play_pause(long *playedp,
389 void *data);
390.fi
391.IP
c0c23a60
RK
392Pauses the current track, for players that support pausing.
393This function must never block, as it runs inside the main loop of the
460b9539 394server.
395.IP
396On success, should return 0 and set \fB*playedp\fR to the number of
397seconds played so far of this track, or to -1 if this cannot be
398determined.
399.IP
400On error, should return -1.
401.PP
402.nf
403\fBvoid disorder_play_resume(void *data);
404.fi
405.IP
c0c23a60
RK
406Resume playing the current track after a pause.
407This function must never block, as it runs inside the main loop of the server.
460b9539 408.SH NOTES
409There is no special DisOrder library to link against; the symbols are
c0c23a60 410exported by the executables themselves.
460b9539 411(You should NOT try to link against \fB-ldisorder\fR.)
412Plugins must be separately
413linked against any other libraries they require, even if the DisOrder
414executables are already linked against them.
415.PP
416The easiest approach is probably to develop the plugin inside the
c0c23a60
RK
417DisOrder tree; then you can just use DisOrder's build system.
418This might also make it easier to submit patches if you write something of
460b9539 419general utility.
420.PP
421Failing that you can use Libtool, if you make sure to pass the
c0c23a60
RK
422\fB-module\fR option.
423For current versions of DisOrder you only need the shared object
424itself, not the \fB.la\fR file.
460b9539 425.PP
426If you know the right runes for your toolchain you could also build
427the modules more directly.
428.PP
429It is possible, up to a point, to implement several plugin interfaces
c0c23a60
RK
430from within a single shared object.
431If you ever use any of the functions that are listed as only being
432available in server plugins, though, then you can only use the
433resulting shared object as a server plugin.
460b9539 434.SH "SEE ALSO"
435.BR disorderd (8),
436.BR disorder (1),
437.BR disorder_config (5)
438.\" Local Variables:
439.\" mode:nroff
440.\" End: