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