chiark / gitweb /
Start on 'settings' window. Currently disabled as it's not very
[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.
b6579a61
RK
80.IP
81These functions will cope with UTF-8 even if the current locale uses
82some other encoding.
460b9539 83.PP
84"Never fail" in the above means that the process is terminated on error.
85.SH LOGGING
86Standard error doesn't reliably go anywhere in current versions of DisOrder,
87and whether syslog is to be used varies depending on how the program is
88invoked. Therefore plugins should use these functions to log any errors or
89informational messages.
90.PP
91.nf
92\fBvoid disorder_error(int errno_value, const char *fmt, ...);
93.fi
94.IP
95Log an error message. If \fBerrno_value\fR is not 0 then the relevant
96string is included in the error message.
97.PP
98.nf
99\fBvoid disorder_fatal(int errno_value, const char *fmt, ...);
100.fi
101.IP
102Log an error message and then terminate the process. If
103\fBerrno_value\fR is not 0 then the relevant string is included in the
104error message.
105.IP
106.B disorder_fatal
107is the right way to terminate the process if a fatal error arises.
108You shouldn't usually try to use \fBexit\fR(3) or \fB_exit\fR(2).
109.PP
110.nf
111\fBvoid disorder_info(const char *fmt, ...);
112.fi
113.IP
114Log a message.
115.IP
116.SH "TRACK DATABASE"
117The functions in this section provide a way of accessing the track database.
118In server plugins these access the database directly; in client plugins the
119requests are transmitted to the server over a socket.
120.PP
121All strings in this section are encoded using UTF-8.
122.PP
123.nf
124\fBint disorder_track_exists(const char *track);
125.fi
126.IP
127This function returns non-0 if \fBtrack\fR exists and 0 if it does
128not.
129.PP
130.nf
131\fBconst char *disorder_track_get_data(const char *track,
132 const char *key);
133.fi
134.IP
135This function looks up the value of \fBkey\fR for \fBtrack\fR and
136returns a pointer to a copy of it. Do not bother to free the pointer.
137If the track or key are not found a null pointer is returned.
138.PP
139.nf
140\fBint disorder_track_set_data(const char *track,
141 const char *key,
142 const char *value);
143.fi
144.IP
145This function sets the value of \fBkey\fR for \fBtrack\fR to
146\fBvalue\fR. On success, 0 is returned; on error, -1 is returned.
147.IP
148If \fBvalue\fR is a null pointer then the preference is deleted.
149.IP
150Values starting with an underscore are stored in the tracks database,
151and are lost if the track is deleted; they should only ever have
152values that can be regenerated on demand. Other values are stored in
153the prefs database and never get automatically deleted.
154.PP
155.nf
156\fBconst char *disorder_track_random(void)
157.fi
158.IP
159Returns a pointer to a copy of the name of a randomly chosen track.
160Each non-alias track has an equal probability of being chosen.
161Aliases are never returned.
162Only available in server plugins.
163.SH "PLUGIN FUNCTIONS"
164This section describes the functions that you must implement to write various
165plugins. All of the plugins have at least one standard implementation
166available in the DisOrder source.
167.PP
168Some functions are listed as only available in server plugins.
169Currently this means that they are not even defined outside the
170server.
171.PP
172All strings in this section are encoded using UTF-8.
b6579a61
RK
173.SS "Tracklength Plugins"
174These are server plugins defined by the \fBtracklength\fR directive.
460b9539 175.PP
176.nf
177\fBlong disorder_tracklength(const char *track,
178 const char *path);
179.fi
180.IP
181Called to calculate the length of a track. \fBtrack\fR is the track
182name (UTF-8) and \fBpath\fR is the path name if there was one, or a
183null pointer otherwise. \fBpath\fR will be the same byte string return from
184the scanner plugin, and so presumably encoded according to the
185filesystem encoding.
186.IP
b6579a61
RK
187To clarify this point, if the track must be opened to compute its
188length, you would normally use \fBpath\fR and not \fBtrack\fR.
189.IP
460b9539 190If the return value is positive it should be the track length in
191seconds (round up if it is not an integral number of seconds long).
192.IP
193If the return value is zero then the track length is unknown.
194.IP
195If the return value is negative then an error occurred determining the
196track length.
197.PP
198Tracklength plugins are invoked from a subprocess of the server, so
199they can block without disturbing the server's operation.
200.SS notify.so
201This is a server plugin.
202.PP
203.nf
204\fBvoid disorder_notify_play(const char *track,
205 const char *submitter);
206.fi
207.IP
208Called when \fBtrack\fR is about to be played. \fBsubmitter\fR identifies the
209submitter or is a null pointer if the track was picked for random play.
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
218Called when \fBtrack\fR is scratched by \fBscratcher\fR. \fBsubmitter\fR
219identifies the submitter or is a null pointer if the track was picked for
220random play. \fBseconds\fR is the number of seconds since the track started
221playing.
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
229occurred though). \fBsubmitter\fR identifies the submitter or is a null
230pointer if the track was picked for random play.
231.PP
232.nf
233\fBvoid disorder_notify_queue(const char *track,
234 const char *submitter);
235.fi
236.IP
237Called when \fBtrack\fR is added to the queue by \fBsubmitter\fR
238(which is never a null pointer). Not called for scratches.
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
279Write a list of files below \fBroot\fR to standard output. Each
280filename should be in the encoding defined for this root in the
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
294Check whether file \fBpath\fR under \fBroot\fR still exists. Should
295return 1 if it exists, 0 if it does not and -1 on error. This is run
296in the main server process.
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
310This defines the player type and capabilities. It should consist of a
311single type value ORed with any number of capability values. The
312following are known type values:
313.RS
314.TP
315.B DISORDER_PLAYER_STANDALONE
316A standalone player that writes directly to some suitable audio
317device.
318.TP
319.B DISORDER_PLAYER_RAW
320A player that writes raw samples to \fB$DISORDER_RAW_FD\fR, for
321instance by using the \fBdisorder\fR libao driver.
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.
339\fBtrack\fR is the name of the track in UTF-8. This function must
340never block, as it runs inside the main loop of the server.
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
350instance to release the memory used by \fBdata\fR. This function must
351never block, as it runs inside the main loop of the server.
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
366\fBtrack\fR is the path name converted to UTF-8. This value (possibly
367converted to some other encoding) should be used in any logs, etc.
368.IP
369If there is no meaningful path, or if the track is a scratch (where no
370filename encoding information is available), \fBpath\fR will be equal
371to \fBtrack\fR.
372.IP
373The parameters are any additional arguments
374supplied to the \fBplayer\fR configuration file command.
375.IP
376This function is always called inside a fork, and it should not return
377until playing has finished.
378.IP
379DisOrder sends the subprocess a signal if the track is to be scratched
380(and when \fBdisorderd\fR is shut down). By default this signal is
381\fBSIGKILL\fR but it can be reconfigured.
382.PP
383.nf
384\fBint disorder_play_pause(long *playedp,
385 void *data);
386.fi
387.IP
388Pauses the current track, for players that support pausing. This
389function must never block, as it runs inside the main loop of the
390server.
391.IP
392On success, should return 0 and set \fB*playedp\fR to the number of
393seconds played so far of this track, or to -1 if this cannot be
394determined.
395.IP
396On error, should return -1.
397.PP
398.nf
399\fBvoid disorder_play_resume(void *data);
400.fi
401.IP
402Resume playing the current track after a pause. This function must
403never block, as it runs inside the main loop of the server.
404.SH NOTES
405There is no special DisOrder library to link against; the symbols are
406exported by the executables themselves.
407(You should NOT try to link against \fB-ldisorder\fR.)
408Plugins must be separately
409linked against any other libraries they require, even if the DisOrder
410executables are already linked against them.
411.PP
412The easiest approach is probably to develop the plugin inside the
413DisOrder tree; then you can just use DisOrder's build system. This
414might also make it easier to submit patches if you write something of
415general utility.
416.PP
417Failing that you can use Libtool, if you make sure to pass the
418\fB-module\fR option. For current versions of DisOrder you only need
419the shared object itself, not the \fB.la\fR file.
420.PP
421If you know the right runes for your toolchain you could also build
422the modules more directly.
423.PP
424It is possible, up to a point, to implement several plugin interfaces
425from within a single shared object. If you ever use any of the
426functions that are listed as only being available in server plugins,
427though, then you can only use the resulting shared object as a server
428plugin.
429.SH "SEE ALSO"
430.BR disorderd (8),
431.BR disorder (1),
432.BR disorder_config (5)
433.\" Local Variables:
434.\" mode:nroff
435.\" End: