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