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