chiark - git - mdw - disorder/blob - 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 .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: