chiark / gitweb /
examples/disorder.init.in: Read settings from `/etc/default/disorder'.
[disorder] / lib / disorder.h
CommitLineData
460b9539 1/*
2 * This file is part of DisOrder.
5aff007d 3 * Copyright (C) 2004-2008 Richard Kettlewell
460b9539 4 *
e7eb3a27 5 * This program is free software: you can redistribute it and/or modify
460b9539 6 * it under the terms of the GNU General Public License as published by
e7eb3a27 7 * the Free Software Foundation, either version 3 of the License, or
460b9539 8 * (at your option) any later version.
e7eb3a27
RK
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 *
460b9539 15 * You should have received a copy of the GNU General Public License
e7eb3a27 16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
460b9539 17 */
18
19#ifndef DISORDER_H
20#define DISORDER_H
21
0b861e97 22#include <stddef.h>
23
460b9539 24#ifdef __cplusplus
25extern "C" {
26#endif
27
16b0fea8
RK
28#ifdef __GNUC__
29# define DISORDER_IFGNUC(x) x
30#else
31# define DISORDER_IFGNUC(x)
32#endif
33
460b9539 34/* memory allocation **********************************************************/
35
36void *disorder_malloc(size_t);
37void *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
44void *disorder_malloc_noptr(size_t);
45void *disorder_realloc_noptr(void *, size_t);
46char *disorder_strdup(const char *);
47char *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
460b9539 56int disorder_snprintf(char buffer[], size_t bufsize, const char *fmt, ...)
16b0fea8 57 DISORDER_IFGNUC(__attribute__((format (printf, 3, 4))));
460b9539 58/* like snprintf */
59
60int disorder_asprintf(char **rp, const char *fmt, ...)
16b0fea8 61 DISORDER_IFGNUC(__attribute__((format (printf, 2, 3))));
460b9539 62/* like asprintf but uses xmalloc_noptr() */
63
460b9539 64/* logging ********************************************************************/
65
16b0fea8
RK
66void disorder_error(int errno_value, const char *fmt, ...)
67 DISORDER_IFGNUC(__attribute__((format (printf, 2, 3))));
460b9539 68/* report an error. If errno_value is nonzero then the errno string
69 * is included. */
70
16b0fea8
RK
71void disorder_fatal(int errno_value, const char *fmt, ...)
72 DISORDER_IFGNUC(__attribute__((noreturn))
73 __attribute__((format (printf, 2, 3))));
460b9539 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
78void disorder_info(const char *fmt, ...);
79/* log a message. */
80
81/* track database *************************************************************/
82
83int disorder_track_exists(const char *track);
84/* return true if the track exists. */
85
86const char *disorder_track_get_data(const char *track, const char *key);
87/* get the value for @key@ (xstrdup'd) */
88
89int 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
94const char *disorder_track_random(void); /* server plugins only */
95/* return the name of a random track */
96
97/* plugin interfaces **********************************************************/
98
99long 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
105void disorder_scan(const char *root);
106/* write a list of path names below @root@ to standard output. */
107
108int 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
112void 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
117void 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
124void 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
129void disorder_notify_queue(const char *track,
130 const char *submitter);
131/* @track@ added to the queue by @submitter@ (never a null pointer) */
132
133void disorder_notify_queue_remove(const char *track,
134 const char *remover);
135/* @track@ removed from the queue by @remover@ (never a null pointer) */
136
137void disorder_notify_queue_move(const char *track,
138 const char *mover);
139/* @track@ moved in the queue by @mover@ (never a null pointer) */
140
141void disorder_notify_pause(const char *track,
142 const char *pauser);
143/* TRACK was paused by PAUSER (might be a null pointer) */
144
145void 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
151extern 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
168void *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
176void 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
185int 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
192void 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
196void 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/*
206Local Variables:
207c-basic-offset:2
208comment-column:40
209End:
210*/