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 | |
ad58ebcc |
145 | int disorder_eclient_connected(const disorder_eclient *c); |
146 | |
460b9539 |
147 | void disorder_eclient_polled(disorder_eclient *c, unsigned mode); |
148 | /* Should be called when c's FD is readable and/or writable, and in any case |
149 | * from time to time (so that retries work). */ |
150 | |
151 | int disorder_eclient_version(disorder_eclient *c, |
152 | disorder_eclient_string_response *completed, |
153 | void *v); |
154 | /* fetch the server version */ |
155 | |
156 | int disorder_eclient_play(disorder_eclient *c, |
157 | const char *track, |
158 | disorder_eclient_no_response *completed, |
159 | void *v); |
160 | /* add a track to the queue */ |
161 | |
162 | int disorder_eclient_pause(disorder_eclient *c, |
163 | disorder_eclient_no_response *completed, |
164 | void *v); |
165 | /* add a track to the queue */ |
166 | |
167 | int disorder_eclient_resume(disorder_eclient *c, |
168 | disorder_eclient_no_response *completed, |
169 | void *v); |
170 | /* add a track to the queue */ |
171 | |
172 | int disorder_eclient_scratch(disorder_eclient *c, |
173 | const char *id, |
174 | disorder_eclient_no_response *completed, |
175 | void *v); |
176 | /* scratch a track by ID */ |
177 | |
178 | int disorder_eclient_scratch_playing(disorder_eclient *c, |
179 | disorder_eclient_no_response *completed, |
180 | void *v); |
181 | /* scratch the playing track whatever it is */ |
182 | |
183 | int disorder_eclient_remove(disorder_eclient *c, |
184 | const char *id, |
185 | disorder_eclient_no_response *completed, |
186 | void *v); |
187 | /* remove a track from the queue */ |
188 | |
189 | int disorder_eclient_moveafter(disorder_eclient *c, |
190 | const char *target, |
191 | int nids, |
192 | const char **ids, |
193 | disorder_eclient_no_response *completed, |
194 | void *v); |
195 | /* move tracks within the queue */ |
196 | |
197 | int disorder_eclient_playing(disorder_eclient *c, |
198 | disorder_eclient_queue_response *completed, |
199 | void *v); |
200 | /* find the currently playing track (0 for none) */ |
201 | |
202 | int disorder_eclient_queue(disorder_eclient *c, |
203 | disorder_eclient_queue_response *completed, |
204 | void *v); |
205 | /* list recently played tracks */ |
206 | |
207 | int disorder_eclient_recent(disorder_eclient *c, |
208 | disorder_eclient_queue_response *completed, |
209 | void *v); |
210 | /* list recently played tracks */ |
211 | |
212 | int disorder_eclient_files(disorder_eclient *c, |
213 | disorder_eclient_list_response *completed, |
214 | const char *dir, |
215 | const char *re, |
216 | void *v); |
217 | /* list files in a directory, matching RE if not a null pointer */ |
218 | |
219 | int disorder_eclient_dirs(disorder_eclient *c, |
220 | disorder_eclient_list_response *completed, |
221 | const char *dir, |
222 | const char *re, |
223 | void *v); |
224 | /* list directories in a directory, matching RE if not a null pointer */ |
225 | |
226 | int disorder_eclient_namepart(disorder_eclient *c, |
227 | disorder_eclient_string_response *completed, |
228 | const char *track, |
229 | const char *context, |
230 | const char *part, |
231 | void *v); |
232 | /* look up a track name part */ |
233 | |
234 | int disorder_eclient_length(disorder_eclient *c, |
235 | disorder_eclient_integer_response *completed, |
236 | const char *track, |
237 | void *v); |
238 | /* look up a track name length */ |
239 | |
240 | int disorder_eclient_volume(disorder_eclient *c, |
241 | disorder_eclient_volume_response *callback, |
242 | int l, int r, |
243 | void *v); |
244 | /* If L and R are both -ve gets the volume. |
245 | * If neither are -ve then sets the volume. |
246 | * Otherwise asserts! |
247 | */ |
248 | |
249 | int disorder_eclient_enable(disorder_eclient *c, |
250 | disorder_eclient_no_response *callback, |
251 | void *v); |
252 | int disorder_eclient_disable(disorder_eclient *c, |
253 | disorder_eclient_no_response *callback, |
254 | void *v); |
255 | int disorder_eclient_random_enable(disorder_eclient *c, |
256 | disorder_eclient_no_response *callback, |
257 | void *v); |
258 | int disorder_eclient_random_disable(disorder_eclient *c, |
259 | disorder_eclient_no_response *callback, |
260 | void *v); |
261 | /* Enable/disable play/random play */ |
262 | |
263 | int disorder_eclient_resolve(disorder_eclient *c, |
264 | disorder_eclient_string_response *completed, |
265 | const char *track, |
266 | void *v); |
267 | /* Resolve aliases */ |
268 | |
269 | int disorder_eclient_log(disorder_eclient *c, |
270 | const disorder_eclient_log_callbacks *callbacks, |
271 | void *v); |
272 | /* Make this a log client (forever - it automatically becomes one again upon |
273 | * reconnection) */ |
274 | |
275 | int disorder_eclient_get(disorder_eclient *c, |
276 | disorder_eclient_string_response *completed, |
277 | const char *track, const char *pref, |
278 | void *v); |
279 | int disorder_eclient_set(disorder_eclient *c, |
280 | disorder_eclient_no_response *completed, |
281 | const char *track, const char *pref, |
282 | const char *value, |
283 | void *v); |
284 | int disorder_eclient_unset(disorder_eclient *c, |
285 | disorder_eclient_no_response *completed, |
286 | const char *track, const char *pref, |
287 | void *v); |
288 | /* Get/set preference values */ |
289 | |
290 | int disorder_eclient_search(disorder_eclient *c, |
291 | disorder_eclient_list_response *completed, |
292 | const char *terms, |
293 | void *v); |
294 | |
295 | #endif |
296 | |
297 | /* |
298 | Local Variables: |
299 | c-basic-offset:2 |
300 | comment-column:40 |
301 | fill-column:79 |
302 | indent-tabs-mode:nil |
303 | End: |
304 | */ |