460b9539 |
1 | /* |
2 | * This file is part of DisOrder. |
3 | * Copyright (C) 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 | */ |
0e4472a0 |
20 | /** @file lib/eclient.h |
21 | * @brief Client code for event-driven programs |
22 | */ |
460b9539 |
23 | |
24 | #ifndef ECLIENT_H |
25 | #define ECLIENT_H |
26 | |
5626f6d2 |
27 | /* Asynchronous client interface */ |
460b9539 |
28 | |
0e4472a0 |
29 | /** @brief Handle type */ |
460b9539 |
30 | typedef struct disorder_eclient disorder_eclient; |
31 | |
32 | struct queue_entry; |
33 | |
0e4472a0 |
34 | /** @brief Set to read from the FD */ |
35 | #define DISORDER_POLL_READ 1u |
36 | |
37 | /** @brief Set to write to the FD */ |
38 | #define DISORDER_POLL_WRITE 2u |
460b9539 |
39 | |
0e4472a0 |
40 | /** @brief Callbacks for all clients |
41 | * |
42 | * These must all be valid. |
43 | */ |
460b9539 |
44 | typedef struct disorder_eclient_callbacks { |
0e4472a0 |
45 | /** @brief Called when a communication error (e.g. connected refused) occurs. |
46 | * @param u from disorder_eclient_new() |
47 | * @param msg error message |
48 | */ |
460b9539 |
49 | void (*comms_error)(void *u, const char *msg); |
460b9539 |
50 | |
0e4472a0 |
51 | /** @brief Called when a command fails (including initial authorization). |
52 | * @param u from disorder_eclient_new() |
53 | * @param v from failed command, or NULL if during setup |
54 | * @param msg error message |
55 | */ |
460b9539 |
56 | void (*protocol_error)(void *u, void *v, int code, const char *msg); |
0e4472a0 |
57 | |
58 | /** @brief Set poll/select flags |
59 | * @param u from disorder_eclient_new() |
60 | * @param c handle |
61 | * @param fd file descriptor |
62 | * @param mode bitmap (@ref DISORDER_POLL_READ and/or @ref DISORDER_POLL_WRITE) |
63 | * |
64 | * Before @p fd is closed you will always get a call with @p mode = 0. |
65 | */ |
460b9539 |
66 | void (*poll)(void *u, disorder_eclient *c, int fd, unsigned mode); |
460b9539 |
67 | |
0e4472a0 |
68 | /** @brief Report current activity |
69 | * @param u from disorder_eclient_new() |
70 | * @param msg Current activity or NULL |
71 | * |
72 | * Called with @p msg = NULL when there's nothing going on. |
73 | */ |
460b9539 |
74 | void (*report)(void *u, const char *msg); |
460b9539 |
75 | } disorder_eclient_callbacks; |
76 | |
0e4472a0 |
77 | /** @brief Callbacks for log clients |
78 | * |
79 | * All of these are allowed to be a null pointers in which case you don't get |
80 | * told about that log event. |
81 | * |
82 | * See disorder_protocol(5) for full documentation. |
83 | */ |
460b9539 |
84 | typedef struct disorder_eclient_log_callbacks { |
0e4472a0 |
85 | /** @brief Called on (re-)connection */ |
460b9539 |
86 | void (*connected)(void *v); |
460b9539 |
87 | |
88 | void (*completed)(void *v, const char *track); |
89 | void (*failed)(void *v, const char *track, const char *status); |
90 | void (*moved)(void *v, const char *user); |
91 | void (*playing)(void *v, const char *track, const char *user/*maybe 0*/); |
92 | void (*queue)(void *v, struct queue_entry *q); |
93 | void (*recent_added)(void *v, struct queue_entry *q); |
94 | void (*recent_removed)(void *v, const char *id); |
95 | void (*removed)(void *v, const char *id, const char *user/*maybe 0*/); |
96 | void (*scratched)(void *v, const char *track, const char *user); |
97 | void (*state)(void *v, unsigned long state); |
98 | void (*volume)(void *v, int left, int right); |
99 | } disorder_eclient_log_callbacks; |
100 | |
101 | /* State bits */ |
0e4472a0 |
102 | |
103 | /** @brief Play is enabled */ |
104 | #define DISORDER_PLAYING_ENABLED 0x00000001 |
105 | |
106 | /** @brief Random play is enabled */ |
107 | #define DISORDER_RANDOM_ENABLED 0x00000002 |
108 | |
109 | /** @brief Track is paused */ |
110 | #define DISORDER_TRACK_PAUSED 0x00000004 |
460b9539 |
111 | |
112 | struct queue_entry; |
113 | struct kvp; |
114 | struct sink; |
115 | |
116 | /* Completion callbacks. These provide the result of operations to the caller. |
117 | * It is always allowed for these to be null pointers if you don't care about |
118 | * the result. */ |
119 | |
120 | typedef void disorder_eclient_no_response(void *v); |
121 | /* completion callback with no data */ |
122 | |
123 | typedef void disorder_eclient_string_response(void *v, const char *value); |
124 | /* completion callback with a string result */ |
125 | |
126 | typedef void disorder_eclient_integer_response(void *v, long value); |
127 | /* completion callback with a integer result */ |
128 | |
129 | typedef void disorder_eclient_volume_response(void *v, int l, int r); |
130 | /* completion callback with a pair of integer results */ |
131 | |
132 | typedef void disorder_eclient_queue_response(void *v, struct queue_entry *q); |
133 | /* completion callback for queue/recent listing */ |
134 | |
135 | typedef void disorder_eclient_list_response(void *v, int nvec, char **vec); |
136 | /* completion callback for file listing etc */ |
137 | |
138 | disorder_eclient *disorder_eclient_new(const disorder_eclient_callbacks *cb, |
139 | void *u); |
140 | /* Create a new client */ |
141 | |
142 | void disorder_eclient_close(disorder_eclient *c); |
143 | /* Close C */ |
144 | |
145 | void disorder_eclient_polled(disorder_eclient *c, unsigned mode); |
146 | /* Should be called when c's FD is readable and/or writable, and in any case |
147 | * from time to time (so that retries work). */ |
148 | |
149 | int disorder_eclient_version(disorder_eclient *c, |
150 | disorder_eclient_string_response *completed, |
151 | void *v); |
152 | /* fetch the server version */ |
153 | |
154 | int disorder_eclient_play(disorder_eclient *c, |
155 | const char *track, |
156 | disorder_eclient_no_response *completed, |
157 | void *v); |
158 | /* add a track to the queue */ |
159 | |
160 | int disorder_eclient_pause(disorder_eclient *c, |
161 | disorder_eclient_no_response *completed, |
162 | void *v); |
163 | /* add a track to the queue */ |
164 | |
165 | int disorder_eclient_resume(disorder_eclient *c, |
166 | disorder_eclient_no_response *completed, |
167 | void *v); |
168 | /* add a track to the queue */ |
169 | |
170 | int disorder_eclient_scratch(disorder_eclient *c, |
171 | const char *id, |
172 | disorder_eclient_no_response *completed, |
173 | void *v); |
174 | /* scratch a track by ID */ |
175 | |
176 | int disorder_eclient_scratch_playing(disorder_eclient *c, |
177 | disorder_eclient_no_response *completed, |
178 | void *v); |
179 | /* scratch the playing track whatever it is */ |
180 | |
181 | int disorder_eclient_remove(disorder_eclient *c, |
182 | const char *id, |
183 | disorder_eclient_no_response *completed, |
184 | void *v); |
185 | /* remove a track from the queue */ |
186 | |
187 | int disorder_eclient_moveafter(disorder_eclient *c, |
188 | const char *target, |
189 | int nids, |
190 | const char **ids, |
191 | disorder_eclient_no_response *completed, |
192 | void *v); |
193 | /* move tracks within the queue */ |
194 | |
195 | int disorder_eclient_playing(disorder_eclient *c, |
196 | disorder_eclient_queue_response *completed, |
197 | void *v); |
198 | /* find the currently playing track (0 for none) */ |
199 | |
200 | int disorder_eclient_queue(disorder_eclient *c, |
201 | disorder_eclient_queue_response *completed, |
202 | void *v); |
203 | /* list recently played tracks */ |
204 | |
205 | int disorder_eclient_recent(disorder_eclient *c, |
206 | disorder_eclient_queue_response *completed, |
207 | void *v); |
208 | /* list recently played tracks */ |
209 | |
210 | int disorder_eclient_files(disorder_eclient *c, |
211 | disorder_eclient_list_response *completed, |
212 | const char *dir, |
213 | const char *re, |
214 | void *v); |
215 | /* list files in a directory, matching RE if not a null pointer */ |
216 | |
217 | int disorder_eclient_dirs(disorder_eclient *c, |
218 | disorder_eclient_list_response *completed, |
219 | const char *dir, |
220 | const char *re, |
221 | void *v); |
222 | /* list directories in a directory, matching RE if not a null pointer */ |
223 | |
224 | int disorder_eclient_namepart(disorder_eclient *c, |
225 | disorder_eclient_string_response *completed, |
226 | const char *track, |
227 | const char *context, |
228 | const char *part, |
229 | void *v); |
230 | /* look up a track name part */ |
231 | |
232 | int disorder_eclient_length(disorder_eclient *c, |
233 | disorder_eclient_integer_response *completed, |
234 | const char *track, |
235 | void *v); |
236 | /* look up a track name length */ |
237 | |
238 | int disorder_eclient_volume(disorder_eclient *c, |
239 | disorder_eclient_volume_response *callback, |
240 | int l, int r, |
241 | void *v); |
242 | /* If L and R are both -ve gets the volume. |
243 | * If neither are -ve then sets the volume. |
244 | * Otherwise asserts! |
245 | */ |
246 | |
247 | int disorder_eclient_enable(disorder_eclient *c, |
248 | disorder_eclient_no_response *callback, |
249 | void *v); |
250 | int disorder_eclient_disable(disorder_eclient *c, |
251 | disorder_eclient_no_response *callback, |
252 | void *v); |
253 | int disorder_eclient_random_enable(disorder_eclient *c, |
254 | disorder_eclient_no_response *callback, |
255 | void *v); |
256 | int disorder_eclient_random_disable(disorder_eclient *c, |
257 | disorder_eclient_no_response *callback, |
258 | void *v); |
259 | /* Enable/disable play/random play */ |
260 | |
261 | int disorder_eclient_resolve(disorder_eclient *c, |
262 | disorder_eclient_string_response *completed, |
263 | const char *track, |
264 | void *v); |
265 | /* Resolve aliases */ |
266 | |
267 | int disorder_eclient_log(disorder_eclient *c, |
268 | const disorder_eclient_log_callbacks *callbacks, |
269 | void *v); |
270 | /* Make this a log client (forever - it automatically becomes one again upon |
271 | * reconnection) */ |
272 | |
273 | int disorder_eclient_get(disorder_eclient *c, |
274 | disorder_eclient_string_response *completed, |
275 | const char *track, const char *pref, |
276 | void *v); |
277 | int disorder_eclient_set(disorder_eclient *c, |
278 | disorder_eclient_no_response *completed, |
279 | const char *track, const char *pref, |
280 | const char *value, |
281 | void *v); |
282 | int disorder_eclient_unset(disorder_eclient *c, |
283 | disorder_eclient_no_response *completed, |
284 | const char *track, const char *pref, |
285 | void *v); |
286 | /* Get/set preference values */ |
287 | |
288 | int disorder_eclient_search(disorder_eclient *c, |
289 | disorder_eclient_list_response *completed, |
290 | const char *terms, |
291 | void *v); |
292 | |
293 | #endif |
294 | |
295 | /* |
296 | Local Variables: |
297 | c-basic-offset:2 |
298 | comment-column:40 |
299 | fill-column:79 |
300 | indent-tabs-mode:nil |
301 | End: |
302 | */ |