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