chiark - git - mdw - disorder/blob - 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.  You must provide disorder_client_poll(). */
  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 */