chiark / gitweb /
lib/configuration.c: Remove `type_stringlist', which nothing was using.
[disorder] / 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 */