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