chiark / gitweb /
pinpoint tests for a couple more unicode.c bits
[disorder] / lib / disorder.h
1 /*
2  * This file is part of DisOrder.
3  * Copyright (C) 2004, 2005, 2006 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 */