Commit | Line | Data |
---|---|---|
460b9539 | 1 | .\" |
bf38ab1a | 2 | .\" Copyright (C) 2004-2008, 2013 Richard Kettlewell |
460b9539 | 3 | .\" |
e7eb3a27 | 4 | .\" This program is free software: you can redistribute it and/or modify |
460b9539 | 5 | .\" it under the terms of the GNU General Public License as published by |
e7eb3a27 | 6 | .\" the Free Software Foundation, either version 3 of the License, or |
460b9539 | 7 | .\" (at your option) any later version. |
e7eb3a27 RK |
8 | .\" |
9 | .\" This program is distributed in the hope that it will be useful, | |
10 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 | .\" GNU General Public License for more details. | |
13 | .\" | |
460b9539 | 14 | .\" You should have received a copy of the GNU General Public License |
e7eb3a27 | 15 | .\" along with this program. If not, see <http://www.gnu.org/licenses/>. |
460b9539 | 16 | .\" |
17 | .TH disorder 3 | |
18 | .SH NAME | |
19 | disorder \- plugin interface to DisOrder jukebox | |
20 | .SH SYNOPSIS | |
21 | .B "#include <disorder.h>" | |
22 | .SH DESCRIPTION | |
23 | This header file defines the plugin interface to DisOrder. | |
24 | .PP | |
25 | The first half of this man page describes the functions DisOrder | |
26 | provides to plugins; the second half describes the functions that | |
27 | plugins must provide. | |
28 | .SH "MEMORY ALLOCATION" | |
c0c23a60 RK |
29 | DisOrder uses a garbage collector internally. |
30 | Therefore it is recommended that plugins use the provided memory | |
31 | allocation interface, rather than calling \fBmalloc\fR(3) etc directly. | |
460b9539 | 32 | .PP |
33 | .nf | |
34 | \fBvoid *disorder_malloc(size_t); | |
35 | void *disorder_realloc(void *, size_t); | |
36 | .fi | |
37 | .IP | |
38 | These functions behave much like \fBmalloc\fR(3) and \fBrealloc\fR(3) | |
39 | except that they never fail; they always zero out the memory | |
40 | allocated; and you do not need to free the result. | |
41 | .IP | |
42 | They may still return a null pointer if asked for a 0-sized | |
43 | allocation. | |
44 | .PP | |
45 | .nf | |
46 | \fBvoid *disorder_malloc_noptr(size_t); | |
47 | void *disorder_realloc_noptr(void *, size_t); | |
48 | .fi | |
49 | .IP | |
50 | These functions are like \fBmalloc\fR(3) and \fBrealloc\fR(3) | |
51 | except that they never fail and you must not put any pointer | |
52 | values in the allocated memory. | |
53 | .IP | |
54 | They may still return a null pointer if asked for a 0-sized | |
c0c23a60 RK |
55 | allocation. |
56 | They do not guarantee to zero out the memory allocated. | |
460b9539 | 57 | .PP |
58 | .nf | |
59 | \fBchar *disorder_strdup(const char *); | |
60 | char *disorder_strndup(const char *, size_t); | |
61 | .fi | |
62 | .IP | |
63 | These functions are like \fBstrdup\fR(3) and \fBstrndup\fR(3) except | |
64 | that they never fail and you do not need to free the result. | |
65 | .PP | |
66 | .nf | |
67 | \fBint disorder_asprintf(char **rp, const char *fmt, ...); | |
68 | int disorder_snprintf(char buffer[], size_t bufsize, | |
69 | const char *fmt, ...); | |
70 | .fi | |
71 | .IP | |
72 | These function are like \fBsnprintf\fR(3) and \fBasprintf\fR(3). | |
73 | .B disorder_asprintf | |
74 | never fails on memory allocation and | |
75 | you do not need to free the results. | |
76 | .IP | |
77 | Floating point conversions and wide character support are not | |
78 | currently implemented. | |
b6579a61 RK |
79 | .IP |
80 | These functions will cope with UTF-8 even if the current locale uses | |
81 | some other encoding. | |
460b9539 | 82 | .PP |
83 | "Never fail" in the above means that the process is terminated on error. | |
84 | .SH LOGGING | |
85 | Standard error doesn't reliably go anywhere in current versions of DisOrder, | |
86 | and whether syslog is to be used varies depending on how the program is | |
c0c23a60 RK |
87 | invoked. |
88 | Therefore plugins should use these functions to log any errors or | |
460b9539 | 89 | informational messages. |
90 | .PP | |
91 | .nf | |
92 | \fBvoid disorder_error(int errno_value, const char *fmt, ...); | |
93 | .fi | |
94 | .IP | |
c0c23a60 RK |
95 | Log an error message. |
96 | If \fBerrno_value\fR is not 0 then the relevant | |
460b9539 | 97 | string is included in the error message. |
98 | .PP | |
99 | .nf | |
100 | \fBvoid disorder_fatal(int errno_value, const char *fmt, ...); | |
101 | .fi | |
102 | .IP | |
c0c23a60 RK |
103 | Log an error message and then terminate the process. |
104 | If \fBerrno_value\fR is not 0 then the relevant string is included in the | |
460b9539 | 105 | error message. |
106 | .IP | |
107 | .B disorder_fatal | |
108 | is the right way to terminate the process if a fatal error arises. | |
109 | You shouldn't usually try to use \fBexit\fR(3) or \fB_exit\fR(2). | |
110 | .PP | |
111 | .nf | |
112 | \fBvoid disorder_info(const char *fmt, ...); | |
113 | .fi | |
114 | .IP | |
115 | Log a message. | |
116 | .IP | |
117 | .SH "TRACK DATABASE" | |
118 | The functions in this section provide a way of accessing the track database. | |
119 | In server plugins these access the database directly; in client plugins the | |
120 | requests are transmitted to the server over a socket. | |
121 | .PP | |
122 | All strings in this section are encoded using UTF-8. | |
123 | .PP | |
124 | .nf | |
125 | \fBint disorder_track_exists(const char *track); | |
126 | .fi | |
127 | .IP | |
128 | This function returns non-0 if \fBtrack\fR exists and 0 if it does | |
129 | not. | |
130 | .PP | |
131 | .nf | |
132 | \fBconst char *disorder_track_get_data(const char *track, | |
133 | const char *key); | |
134 | .fi | |
135 | .IP | |
136 | This function looks up the value of \fBkey\fR for \fBtrack\fR and | |
c0c23a60 RK |
137 | returns a pointer to a copy of it. |
138 | Do not bother to free the pointer. | |
460b9539 | 139 | If the track or key are not found a null pointer is returned. |
140 | .PP | |
141 | .nf | |
142 | \fBint disorder_track_set_data(const char *track, | |
143 | const char *key, | |
144 | const char *value); | |
145 | .fi | |
146 | .IP | |
147 | This function sets the value of \fBkey\fR for \fBtrack\fR to | |
c0c23a60 | 148 | \fBvalue\fR. |
3db7469f | 149 | On success, 0 is returned; on error, \-1 is returned. |
460b9539 | 150 | .IP |
151 | If \fBvalue\fR is a null pointer then the preference is deleted. | |
152 | .IP | |
153 | Values starting with an underscore are stored in the tracks database, | |
154 | and are lost if the track is deleted; they should only ever have | |
c0c23a60 RK |
155 | values that can be regenerated on demand. |
156 | Other values are stored in the prefs database and never get | |
157 | automatically deleted. | |
460b9539 | 158 | .SH "PLUGIN FUNCTIONS" |
159 | This section describes the functions that you must implement to write various | |
c0c23a60 RK |
160 | plugins. |
161 | All of the plugins have at least one standard implementation available | |
162 | in the DisOrder source. | |
460b9539 | 163 | .PP |
164 | Some functions are listed as only available in server plugins. | |
165 | Currently this means that they are not even defined outside the | |
166 | server. | |
167 | .PP | |
168 | All strings in this section are encoded using UTF-8. | |
b6579a61 RK |
169 | .SS "Tracklength Plugins" |
170 | These are server plugins defined by the \fBtracklength\fR directive. | |
460b9539 | 171 | .PP |
172 | .nf | |
173 | \fBlong disorder_tracklength(const char *track, | |
174 | const char *path); | |
175 | .fi | |
176 | .IP | |
c0c23a60 RK |
177 | Called to calculate the length of a track. |
178 | \fBtrack\fR is the track name (UTF-8) and \fBpath\fR is the path | |
179 | name if there was one, or a null pointer otherwise. | |
180 | \fBpath\fR will be the same byte string return from | |
460b9539 | 181 | the scanner plugin, and so presumably encoded according to the |
182 | filesystem encoding. | |
183 | .IP | |
b6579a61 RK |
184 | To clarify this point, if the track must be opened to compute its |
185 | length, you would normally use \fBpath\fR and not \fBtrack\fR. | |
186 | .IP | |
460b9539 | 187 | If the return value is positive it should be the track length in |
188 | seconds (round up if it is not an integral number of seconds long). | |
189 | .IP | |
190 | If the return value is zero then the track length is unknown. | |
191 | .IP | |
192 | If the return value is negative then an error occurred determining the | |
193 | track length. | |
194 | .PP | |
195 | Tracklength plugins are invoked from a subprocess of the server, so | |
196 | they can block without disturbing the server's operation. | |
197 | .SS notify.so | |
198 | This is a server plugin. | |
199 | .PP | |
200 | .nf | |
201 | \fBvoid disorder_notify_play(const char *track, | |
202 | const char *submitter); | |
203 | .fi | |
204 | .IP | |
c0c23a60 RK |
205 | Called when \fBtrack\fR is about to be played. |
206 | \fBsubmitter\fR identifies the submitter or is a null pointer if | |
207 | the track was picked for random play. | |
460b9539 | 208 | .PP |
209 | .nf | |
210 | \fBvoid disorder_notify_scratch(const char *track, | |
211 | const char *submitter, | |
212 | const char *scratcher, | |
213 | int seconds); | |
214 | .fi | |
215 | .IP | |
c0c23a60 RK |
216 | Called when \fBtrack\fR is scratched by \fBscratcher\fR. |
217 | \fBsubmitter\fR identifies the submitter or is a null pointer if | |
218 | the track was picked for random play. | |
219 | \fBseconds\fR is the number of seconds since the track started playing. | |
460b9539 | 220 | .PP |
221 | .nf | |
222 | \fBvoid disorder_notify_not_scratched(const char *track, | |
223 | const char *submitter); | |
224 | .fi | |
225 | .IP | |
226 | Called when \fBtrack\fR completes without being scratched (an error might have | |
c0c23a60 RK |
227 | occurred though). |
228 | \fBsubmitter\fR identifies the submitter or is a null pointer if the | |
229 | track was picked for random play. | |
460b9539 | 230 | .PP |
231 | .nf | |
232 | \fBvoid disorder_notify_queue(const char *track, | |
233 | const char *submitter); | |
234 | .fi | |
235 | .IP | |
236 | Called when \fBtrack\fR is added to the queue by \fBsubmitter\fR | |
c0c23a60 RK |
237 | (which is never a null pointer). |
238 | Not called for scratches. | |
460b9539 | 239 | .PP |
240 | .nf | |
241 | \fBvoid disorder_notify_queue_remove(const char *track, | |
242 | const char *remover); | |
243 | .fi | |
244 | .IP | |
245 | Called when \fBtrack\fR is removed from queue by \fBremover\fR (which | |
246 | is 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 | |
253 | Called 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 | |
261 | Called 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 | |
269 | Called when \fBtrack\fR is resumed by \fBwho\fR | |
270 | (which might be a null pointer). | |
271 | .SS "Scanner Plugins" | |
272 | Scanner plugins are server plugins and may have any name; they are | |
273 | chosen via the configuration file. | |
274 | .PP | |
275 | .nf | |
276 | \fBvoid disorder_scan(const char *root); | |
277 | .fi | |
278 | .IP | |
c0c23a60 RK |
279 | Write a list of files below \fBroot\fR to standard output. |
280 | Each filename should be in the encoding defined for this root in the | |
460b9539 | 281 | configuration file and should be terminated by character 0. |
282 | .IP | |
283 | It is up to the plugin implementor whether they prefer to use stdio or | |
284 | write to file descriptor 1 directly. | |
285 | .IP | |
286 | All the filenames had better start with \fBroot\fR as this is used to | |
287 | match 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 | |
c0c23a60 | 294 | Check whether file \fBpath\fR under \fBroot\fR still exists. |
3db7469f | 295 | Should return 1 if it exists, 0 if it does not and \-1 on error. |
c0c23a60 | 296 | This is run in the main server process. |
460b9539 | 297 | .PP |
298 | Both scan and recheck are executed inside a subprocess, so it will not | |
299 | break the server if they block for an extended period (though of | |
300 | course, they should not gratuitously take longer than necessary to do | |
301 | their jobs). | |
302 | .SS "Player plugins" | |
303 | Player plugins are server plugins and may have any name; they are | |
304 | chosen via the configuration file. | |
305 | .PP | |
306 | .nf | |
307 | extern const unsigned long disorder_player_type; | |
308 | .fi | |
309 | .IP | |
c0c23a60 RK |
310 | This defines the player type and capabilities. |
311 | It should consist of a single type value ORed with any number of | |
312 | capability values. | |
313 | The following are known type values: | |
460b9539 | 314 | .RS |
315 | .TP | |
316 | .B DISORDER_PLAYER_STANDALONE | |
317 | A standalone player that writes directly to some suitable audio | |
318 | device. | |
319 | .TP | |
320 | .B DISORDER_PLAYER_RAW | |
bf38ab1a RK |
321 | A player that writes blocks of raw samples to \fB$DISORDER_RAW_FD\fR. |
322 | See | |
323 | .B "RAW FORMAT PLAYERS" | |
324 | below. | |
460b9539 | 325 | .RE |
326 | .IP | |
327 | Known capabilities are: | |
328 | .RS | |
329 | .TP | |
330 | .B DISORDER_PLAYER_PREFORK | |
331 | Supports the prefork and cleanup calls. | |
332 | .TP | |
333 | .B DISORDER_PLAYER_PAUSES | |
334 | Supports the pause and resume calls. | |
335 | .RE | |
336 | .PP | |
337 | .nf | |
338 | \fBvoid *disorder_play_prefork(const char *track); | |
339 | .fi | |
340 | .IP | |
341 | Called before a track is played, if \fB_PREFORK\fR is set. | |
c0c23a60 RK |
342 | \fBtrack\fR is the name of the track in UTF-8. |
343 | This function must never block, as it runs inside the main loop of the server. | |
460b9539 | 344 | .IP |
345 | The return value will be passed to the functions below as \fBdata\fR. | |
346 | On error, a null pointer should be returned. | |
347 | .PP | |
348 | .nf | |
349 | \fBvoid disorder_play_cleanup(void *data); | |
350 | .fi | |
351 | .IP | |
352 | Called after a track has been completed, if \fB_PREFORK\fR is set, for | |
c0c23a60 RK |
353 | instance to release the memory used by \fBdata\fR. |
354 | This function must never block, as it runs inside the main loop of the server. | |
460b9539 | 355 | .PP |
356 | .nf | |
357 | \fBvoid disorder_play_track(const char *const *parameters, | |
358 | int nparameters, | |
359 | const char *path, | |
360 | const char *track, | |
361 | void *data); | |
362 | .fi | |
363 | .IP | |
364 | Play a track. | |
365 | .IP | |
366 | \fBpath\fR is the path name as originally encoded in the filesystem. | |
367 | This is the value you should ultimately pass to \fBopen\fR(2). | |
368 | .IP | |
c0c23a60 RK |
369 | \fBtrack\fR is the path name converted to UTF-8. |
370 | This value (possibly converted to some other encoding) should be used | |
371 | in any logs, etc. | |
460b9539 | 372 | .IP |
373 | If there is no meaningful path, or if the track is a scratch (where no | |
374 | filename encoding information is available), \fBpath\fR will be equal | |
375 | to \fBtrack\fR. | |
376 | .IP | |
377 | The parameters are any additional arguments | |
378 | supplied to the \fBplayer\fR configuration file command. | |
379 | .IP | |
380 | This function is always called inside a fork, and it should not return | |
381 | until playing has finished. | |
382 | .IP | |
383 | DisOrder sends the subprocess a signal if the track is to be scratched | |
c0c23a60 RK |
384 | (and when \fBdisorderd\fR is shut down). |
385 | By default this signal is \fBSIGKILL\fR but it can be reconfigured. | |
460b9539 | 386 | .PP |
387 | .nf | |
388 | \fBint disorder_play_pause(long *playedp, | |
389 | void *data); | |
390 | .fi | |
391 | .IP | |
c0c23a60 RK |
392 | Pauses the current track, for players that support pausing. |
393 | This function must never block, as it runs inside the main loop of the | |
460b9539 | 394 | server. |
395 | .IP | |
396 | On success, should return 0 and set \fB*playedp\fR to the number of | |
3db7469f | 397 | seconds played so far of this track, or to \-1 if this cannot be |
460b9539 | 398 | determined. |
399 | .IP | |
3db7469f | 400 | On error, should return \-1. |
460b9539 | 401 | .PP |
402 | .nf | |
403 | \fBvoid disorder_play_resume(void *data); | |
404 | .fi | |
405 | .IP | |
c0c23a60 RK |
406 | Resume playing the current track after a pause. |
407 | This function must never block, as it runs inside the main loop of the server. | |
bf38ab1a RK |
408 | .SH "RAW FORMAT PLAYERS" |
409 | Raw format players should write data to the file descriptor given by | |
410 | the environment variable \fBDISORDER_RAW_FD\fR. | |
411 | .PP | |
412 | The output format is a series of chunks. Each chunk has a header with | |
413 | the following format: | |
414 | .PP | |
415 | .nf | |
416 | struct stream_header { | |
417 | uint32_t nbytes; | |
418 | uint32_t rate; | |
419 | uint8_t channels; | |
420 | uint8_t bits; | |
421 | uint8_t endian; | |
422 | } attribute((packed)); | |
423 | .fi | |
424 | .PP | |
425 | The meanings of the fields are as follows: | |
426 | .TP | |
427 | .B nbytes | |
428 | The total number of bytes of sample data that follow the header. | |
429 | .TP | |
430 | .B rate | |
431 | The sample rate in samples per second. | |
432 | e.g. 44100. | |
433 | .TP | |
434 | .B channels | |
435 | The number of channels per frame. | |
436 | e.g. 2. | |
437 | .TP | |
438 | .B bits | |
439 | The number of bits per sample. | |
440 | e.g. 16. | |
441 | .TP | |
442 | .B endian | |
443 | The sample byte order. | |
444 | 1 for big-endian samples and 2 for little-endian samples. | |
445 | .PP | |
446 | Any number of chunks are allowed. | |
447 | .PP | |
448 | Raw format players may be started before the track is to be played, | |
449 | and (if the track is then removed from the queue before it reaches the | |
450 | head) terminated before the track ever reaches a physical speaker. | |
451 | The point of this is to allow audio data to be ready to play the | |
452 | moment the previous track end, without having to wait for the player | |
453 | to start up. | |
454 | There is no way for a player to tell that this is going on. | |
460b9539 | 455 | .SH NOTES |
456 | There is no special DisOrder library to link against; the symbols are | |
c0c23a60 | 457 | exported by the executables themselves. |
460b9539 | 458 | (You should NOT try to link against \fB-ldisorder\fR.) |
459 | Plugins must be separately | |
460 | linked against any other libraries they require, even if the DisOrder | |
461 | executables are already linked against them. | |
462 | .PP | |
463 | The easiest approach is probably to develop the plugin inside the | |
c0c23a60 RK |
464 | DisOrder tree; then you can just use DisOrder's build system. |
465 | This might also make it easier to submit patches if you write something of | |
460b9539 | 466 | general utility. |
467 | .PP | |
468 | Failing that you can use Libtool, if you make sure to pass the | |
c0c23a60 RK |
469 | \fB-module\fR option. |
470 | For current versions of DisOrder you only need the shared object | |
471 | itself, not the \fB.la\fR file. | |
460b9539 | 472 | .PP |
473 | If you know the right runes for your toolchain you could also build | |
474 | the modules more directly. | |
475 | .PP | |
476 | It is possible, up to a point, to implement several plugin interfaces | |
c0c23a60 RK |
477 | from within a single shared object. |
478 | If you ever use any of the functions that are listed as only being | |
479 | available in server plugins, though, then you can only use the | |
480 | resulting shared object as a server plugin. | |
460b9539 | 481 | .SH "SEE ALSO" |
482 | .BR disorderd (8), | |
483 | .BR disorder (1), | |
484 | .BR disorder_config (5) | |
485 | .\" Local Variables: | |
486 | .\" mode:nroff | |
487 | .\" End: |