chiark - git - mdw - disorder/blob - lib/disorder.h

   1 /*
   2  * This file is part of DisOrder.
   3  * Copyright (C) 2004-2008 Richard Kettlewell
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  18  * USA
  19  */
  20
  21 #ifndef DISORDER_H
  22 #define DISORDER_H
  23
  24 #include <stddef.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /* memory allocation **********************************************************/
  31
  32 void *disorder_malloc(size_t);
  33 void *disorder_realloc(void *, size_t);
  34 /* As malloc/realloc, but
  35  * 1) succeed or call fatal
  36  * 2) always clear (the unused part of) the new allocation
  37  * 3) are garbage-collected
  38  */
  39
  40 void *disorder_malloc_noptr(size_t);
  41 void *disorder_realloc_noptr(void *, size_t);
  42 char *disorder_strdup(const char *);
  43 char *disorder_strndup(const char *, size_t);
  44 /* As malloc/realloc/strdup, but
  45  * 1) succeed or call fatal
  46  * 2) are garbage-collected
  47  * 3) allocated space must not contain any pointers
  48  *
  49  * {xmalloc,xrealloc}_noptr don't promise to clear the new space
  50  */
  51
  52 #ifdef __GNUC__
  53
  54 int disorder_snprintf(char buffer[], size_t bufsize, const char *fmt, ...)
  55   __attribute__((format (printf, 3, 4)));
  56 /* like snprintf */
  57
  58 int disorder_asprintf(char **rp, const char *fmt, ...)
  59   __attribute__((format (printf, 2, 3)));
  60 /* like asprintf but uses xmalloc_noptr() */
  61
  62 #else
  63
  64 int disorder_snprintf(char buffer[], size_t bufsize, const char *fmt, ...);
  65 /* like snprintf */
  66
  67 int disorder_asprintf(char **rp, const char *fmt, ...);
  68 /* like asprintf but uses xmalloc_noptr() */
  69
  70 #endif
  71
  72
  73 /* logging ********************************************************************/
  74
  75 void disorder_error(int errno_value, const char *fmt, ...);
  76 /* report an error.  If errno_value is nonzero then the errno string
  77  * is included. */
  78
  79 void disorder_fatal(int errno_value, const char *fmt, ...);
  80 /* report an error and terminate.  If errno_value is nonzero then the
  81  * errno string is included.  This is the only safe way to terminate
  82  * the process. */
  83
  84 void disorder_info(const char *fmt, ...);
  85 /* log a message. */
  86
  87 /* track database *************************************************************/
  88
  89 int disorder_track_exists(const char *track);
  90 /* return true if the track exists. */
  91
  92 const char *disorder_track_get_data(const char *track, const char *key);
  93 /* get the value for @key@ (xstrdup'd) */
  94
  95 int disorder_track_set_data(const char *track,
  96                             const char *key, const char *value);
  97 /* set the value of @key@ to @value@, or remove it if @value@ is a null
  98  * pointer.  Return 0 on success, -1 on error. */
  99
 100 const char *disorder_track_random(void); /* server plugins only */
 101 /* return the name of a random track */
 102
 103 /* plugin interfaces **********************************************************/
 104
 105 long disorder_tracklength(const char *track, const char *path);
 106 /* compute the length of the track.  @track@ is the UTF-8 name of the
 107  * track, @path@ is the file system name (or 0 for tracks that don't
 108  * exist in the filesystem).  The return value should be a positive
 109  * number of seconds, 0 for unknown or -1 if an error occurred. */
 110
 111 void disorder_scan(const char *root);
 112 /* write a list of path names below @root@ to standard output. */
 113
 114 int disorder_check(const char *root, const char *path);
 115 /* Recheck a track, given its root and path name.  Return 1 if it
 116  * exists, 0 if it does not exist and -1 if an error occurred. */
 117
 118 void disorder_notify_play(const char *track,
 119                           const char *submitter);
 120 /* we're going to play @track@.  It was submitted by @submitter@
 121  * (might be a null pointer) */
 122
 123 void disorder_notify_scratch(const char *track,
 124                              const char *submitter,
 125                              const char *scratcher,
 126                              int seconds);
 127 /* @scratcher@ scratched @track@ after @seconds@.  It was submitted by
 128  * @submitter@ (might be a null pointer) */
 129
 130 void disorder_notify_not_scratched(const char *track,
 131                                    const char *submitter);
 132 /* @track@ (submitted by @submitter@, which might be a null pointer)
 133  * was not scratched. */
 134
 135 void disorder_notify_queue(const char *track,
 136                            const char *submitter);
 137 /* @track@ added to the queue by @submitter@ (never a null pointer) */
 138
 139 void disorder_notify_queue_remove(const char *track,
 140                                   const char *remover);
 141 /* @track@ removed from the queue by @remover@ (never a null pointer) */
 142
 143 void disorder_notify_queue_move(const char *track,
 144                                 const char *mover);
 145 /* @track@ moved in the queue by @mover@ (never a null pointer) */
 146
 147 void disorder_notify_pause(const char *track,
 148                            const char *pauser);
 149 /* TRACK was paused by PAUSER (might be a null pointer) */
 150
 151 void disorder_notify_resume(const char *track,
 152                             const char *resumer);
 153 /* TRACK was resumed by PAUSER (might be a null pointer) */
 154
 155 /* player plugin interface ****************************************************/
 156
 157 extern const unsigned long disorder_player_type;
 158
 159 #define DISORDER_PLAYER_STANDALONE 0x00000000
 160 /* this player plays sound directly */
 161
 162 #define DISORDER_PLAYER_RAW        0x00000001
 163 /* player that sends raw samples to $DISORDER_RAW_FD */
 164
 165 #define DISORDER_PLAYER_TYPEMASK   0x000000ff
 166 /* mask for player types */
 167
 168 #define DISORDER_PLAYER_PREFORK    0x00000100
 169 /* call prefork function */
 170
 171 #define DISORDER_PLAYER_PAUSES     0x00000200
 172 /* supports pausing */
 173
 174 void *disorder_play_prefork(const char *track);
 175 /* Called outside the fork.  Should not block.  Returns a null pointer
 176  * on error.
 177  *
 178  * If _play_prefork is called then its return value is used as the
 179  * DATA argument to the following functions.  Otherwise the value of
 180  * DATA argument is indeterminate and must not be used. */
 181
 182 void disorder_play_track(const char *const *parameters,
 183                          int nparameters,
 184                          const char *path,
 185                          const char *track,
 186                          void *data);
 187 /* Called to play a track.  Should either exec or only return when the
 188  * track has finished.  Should not call exit() (except after a
 189  * succesful exec).  Allowed to call _Exit(). */
 190
 191 int disorder_play_pause(long *playedp, void *data);
 192 /* Pauses the playing track.  If the track can be paused returns 0 and
 193  * stores the number of seconds so far played via PLAYEDP, or sets it
 194  * to -1 if this is not known.  If the track cannot be paused then
 195  * returns -1.  Should not block.
 196  */
 197
 198 void disorder_play_resume(void *data);
 199 /* Restarts play after a pause.  PLAYED is the value returned from the
 200  * original pause operation.  Should not block. */
 201
 202 void disorder_play_cleanup(void *data);
 203 /* called to clean up DATA.  Should not block. */
 204
 205 #ifdef __cplusplus
 206 };
 207 #endif
 208
 209 #endif /* DISORDER_H */
 210
 211 /*
 212 Local Variables:
 213 c-basic-offset:2
 214 comment-column:40
 215 End:
 216 */