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 |
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: |