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