| 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 | .IP |
| 81 | These functions will cope with UTF-8 even if the current locale uses |
| 82 | some other encoding. |
| 83 | .PP |
| 84 | "Never fail" in the above means that the process is terminated on error. |
| 85 | .SH LOGGING |
| 86 | Standard error doesn't reliably go anywhere in current versions of DisOrder, |
| 87 | and whether syslog is to be used varies depending on how the program is |
| 88 | invoked. Therefore plugins should use these functions to log any errors or |
| 89 | informational messages. |
| 90 | .PP |
| 91 | .nf |
| 92 | \fBvoid disorder_error(int errno_value, const char *fmt, ...); |
| 93 | .fi |
| 94 | .IP |
| 95 | Log an error message. If \fBerrno_value\fR is not 0 then the relevant |
| 96 | string is included in the error message. |
| 97 | .PP |
| 98 | .nf |
| 99 | \fBvoid disorder_fatal(int errno_value, const char *fmt, ...); |
| 100 | .fi |
| 101 | .IP |
| 102 | Log an error message and then terminate the process. If |
| 103 | \fBerrno_value\fR is not 0 then the relevant string is included in the |
| 104 | error message. |
| 105 | .IP |
| 106 | .B disorder_fatal |
| 107 | is the right way to terminate the process if a fatal error arises. |
| 108 | You 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 |
| 114 | Log a message. |
| 115 | .IP |
| 116 | .SH "TRACK DATABASE" |
| 117 | The functions in this section provide a way of accessing the track database. |
| 118 | In server plugins these access the database directly; in client plugins the |
| 119 | requests are transmitted to the server over a socket. |
| 120 | .PP |
| 121 | All 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 |
| 127 | This function returns non-0 if \fBtrack\fR exists and 0 if it does |
| 128 | not. |
| 129 | .PP |
| 130 | .nf |
| 131 | \fBconst char *disorder_track_get_data(const char *track, |
| 132 | const char *key); |
| 133 | .fi |
| 134 | .IP |
| 135 | This function looks up the value of \fBkey\fR for \fBtrack\fR and |
| 136 | returns a pointer to a copy of it. Do not bother to free the pointer. |
| 137 | If 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 |
| 145 | This 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 |
| 148 | If \fBvalue\fR is a null pointer then the preference is deleted. |
| 149 | .IP |
| 150 | Values starting with an underscore are stored in the tracks database, |
| 151 | and are lost if the track is deleted; they should only ever have |
| 152 | values that can be regenerated on demand. Other values are stored in |
| 153 | the prefs database and never get automatically deleted. |
| 154 | .PP |
| 155 | .nf |
| 156 | \fBconst char *disorder_track_random(void) |
| 157 | .fi |
| 158 | .IP |
| 159 | Returns a pointer to a copy of the name of a randomly chosen track. |
| 160 | Each non-alias track has an equal probability of being chosen. |
| 161 | Aliases are never returned. |
| 162 | Only available in server plugins. |
| 163 | .SH "PLUGIN FUNCTIONS" |
| 164 | This section describes the functions that you must implement to write various |
| 165 | plugins. All of the plugins have at least one standard implementation |
| 166 | available in the DisOrder source. |
| 167 | .PP |
| 168 | Some functions are listed as only available in server plugins. |
| 169 | Currently this means that they are not even defined outside the |
| 170 | server. |
| 171 | .PP |
| 172 | All strings in this section are encoded using UTF-8. |
| 173 | .SS "Tracklength Plugins" |
| 174 | These are server plugins defined by the \fBtracklength\fR directive. |
| 175 | .PP |
| 176 | .nf |
| 177 | \fBlong disorder_tracklength(const char *track, |
| 178 | const char *path); |
| 179 | .fi |
| 180 | .IP |
| 181 | Called to calculate the length of a track. \fBtrack\fR is the track |
| 182 | name (UTF-8) and \fBpath\fR is the path name if there was one, or a |
| 183 | null pointer otherwise. \fBpath\fR will be the same byte string return from |
| 184 | the scanner plugin, and so presumably encoded according to the |
| 185 | filesystem encoding. |
| 186 | .IP |
| 187 | To clarify this point, if the track must be opened to compute its |
| 188 | length, you would normally use \fBpath\fR and not \fBtrack\fR. |
| 189 | .IP |
| 190 | If the return value is positive it should be the track length in |
| 191 | seconds (round up if it is not an integral number of seconds long). |
| 192 | .IP |
| 193 | If the return value is zero then the track length is unknown. |
| 194 | .IP |
| 195 | If the return value is negative then an error occurred determining the |
| 196 | track length. |
| 197 | .PP |
| 198 | Tracklength plugins are invoked from a subprocess of the server, so |
| 199 | they can block without disturbing the server's operation. |
| 200 | .SS notify.so |
| 201 | This is a server plugin. |
| 202 | .PP |
| 203 | .nf |
| 204 | \fBvoid disorder_notify_play(const char *track, |
| 205 | const char *submitter); |
| 206 | .fi |
| 207 | .IP |
| 208 | Called when \fBtrack\fR is about to be played. \fBsubmitter\fR identifies the |
| 209 | submitter 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 |
| 218 | Called when \fBtrack\fR is scratched by \fBscratcher\fR. \fBsubmitter\fR |
| 219 | identifies the submitter or is a null pointer if the track was picked for |
| 220 | random play. \fBseconds\fR is the number of seconds since the track started |
| 221 | playing. |
| 222 | .PP |
| 223 | .nf |
| 224 | \fBvoid disorder_notify_not_scratched(const char *track, |
| 225 | const char *submitter); |
| 226 | .fi |
| 227 | .IP |
| 228 | Called when \fBtrack\fR completes without being scratched (an error might have |
| 229 | occurred though). \fBsubmitter\fR identifies the submitter or is a null |
| 230 | pointer 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 |
| 237 | Called 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 |
| 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 |
| 279 | Write a list of files below \fBroot\fR to standard output. Each |
| 280 | filename should be in the encoding defined for this root in the |
| 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 |
| 294 | Check whether file \fBpath\fR under \fBroot\fR still exists. Should |
| 295 | return 1 if it exists, 0 if it does not and -1 on error. This is run |
| 296 | in the main server process. |
| 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 |
| 310 | This defines the player type and capabilities. It should consist of a |
| 311 | single type value ORed with any number of capability values. The |
| 312 | following are known type values: |
| 313 | .RS |
| 314 | .TP |
| 315 | .B DISORDER_PLAYER_STANDALONE |
| 316 | A standalone player that writes directly to some suitable audio |
| 317 | device. |
| 318 | .TP |
| 319 | .B DISORDER_PLAYER_RAW |
| 320 | A player that writes raw samples to \fB$DISORDER_RAW_FD\fR, for |
| 321 | instance by using the \fBdisorder\fR libao driver. |
| 322 | .RE |
| 323 | .IP |
| 324 | Known capabilities are: |
| 325 | .RS |
| 326 | .TP |
| 327 | .B DISORDER_PLAYER_PREFORK |
| 328 | Supports the prefork and cleanup calls. |
| 329 | .TP |
| 330 | .B DISORDER_PLAYER_PAUSES |
| 331 | Supports the pause and resume calls. |
| 332 | .RE |
| 333 | .PP |
| 334 | .nf |
| 335 | \fBvoid *disorder_play_prefork(const char *track); |
| 336 | .fi |
| 337 | .IP |
| 338 | Called 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 |
| 340 | never block, as it runs inside the main loop of the server. |
| 341 | .IP |
| 342 | The return value will be passed to the functions below as \fBdata\fR. |
| 343 | On error, a null pointer should be returned. |
| 344 | .PP |
| 345 | .nf |
| 346 | \fBvoid disorder_play_cleanup(void *data); |
| 347 | .fi |
| 348 | .IP |
| 349 | Called after a track has been completed, if \fB_PREFORK\fR is set, for |
| 350 | instance to release the memory used by \fBdata\fR. This function must |
| 351 | never 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 |
| 361 | Play a track. |
| 362 | .IP |
| 363 | \fBpath\fR is the path name as originally encoded in the filesystem. |
| 364 | This 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 |
| 367 | converted to some other encoding) should be used in any logs, etc. |
| 368 | .IP |
| 369 | If there is no meaningful path, or if the track is a scratch (where no |
| 370 | filename encoding information is available), \fBpath\fR will be equal |
| 371 | to \fBtrack\fR. |
| 372 | .IP |
| 373 | The parameters are any additional arguments |
| 374 | supplied to the \fBplayer\fR configuration file command. |
| 375 | .IP |
| 376 | This function is always called inside a fork, and it should not return |
| 377 | until playing has finished. |
| 378 | .IP |
| 379 | DisOrder 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 |
| 388 | Pauses the current track, for players that support pausing. This |
| 389 | function must never block, as it runs inside the main loop of the |
| 390 | server. |
| 391 | .IP |
| 392 | On success, should return 0 and set \fB*playedp\fR to the number of |
| 393 | seconds played so far of this track, or to -1 if this cannot be |
| 394 | determined. |
| 395 | .IP |
| 396 | On error, should return -1. |
| 397 | .PP |
| 398 | .nf |
| 399 | \fBvoid disorder_play_resume(void *data); |
| 400 | .fi |
| 401 | .IP |
| 402 | Resume playing the current track after a pause. This function must |
| 403 | never block, as it runs inside the main loop of the server. |
| 404 | .SH NOTES |
| 405 | There is no special DisOrder library to link against; the symbols are |
| 406 | exported by the executables themselves. |
| 407 | (You should NOT try to link against \fB-ldisorder\fR.) |
| 408 | Plugins must be separately |
| 409 | linked against any other libraries they require, even if the DisOrder |
| 410 | executables are already linked against them. |
| 411 | .PP |
| 412 | The easiest approach is probably to develop the plugin inside the |
| 413 | DisOrder tree; then you can just use DisOrder's build system. This |
| 414 | might also make it easier to submit patches if you write something of |
| 415 | general utility. |
| 416 | .PP |
| 417 | Failing 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 |
| 419 | the shared object itself, not the \fB.la\fR file. |
| 420 | .PP |
| 421 | If you know the right runes for your toolchain you could also build |
| 422 | the modules more directly. |
| 423 | .PP |
| 424 | It is possible, up to a point, to implement several plugin interfaces |
| 425 | from within a single shared object. If you ever use any of the |
| 426 | functions that are listed as only being available in server plugins, |
| 427 | though, then you can only use the resulting shared object as a server |
| 428 | plugin. |
| 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: |