chiark - git - mdw - disorder/blob - lib/queue.h

   1 /*
   2  * This file is part of DisOrder.
   3  * Copyright (C) 2004-2008 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 3 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,
  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  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 /** @file lib/queue.h
  19  * @brief Track queues
  20  *
  21  * Used for the queue, the recently played list and the currently playing
  22  * track, both in the server and in clients.
  23  */
  24 #ifndef QUEUE_H
  25 #define QUEUE_H
  26
  27 #include <time.h>
  28
  29 /** @brief Possible track states */
  30 enum playing_state {
  31   /** @brief Track failed to play */
  32   playing_failed,
  33
  34   /** @brief Track is a scratch and has not been played yet
  35    *
  36    * Going to become obsolete.
  37    */
  38   playing_isscratch,
  39
  40   /** @brief Could not find a player
  41    *
  42    * Obsolete - nothing sets this any more
  43    */
  44   playing_no_player,
  45
  46   /** @brief Play completed successfully
  47    *
  48    * Currently this actually means it finished decoding - it might still be
  49    * buffered in the speaker, RTP player, sound card, etc.
  50    *
  51    * It might also mean that it's a (short!) track that hasn't been played at
  52    * all yet but has been fully decoded ahead of time!  (This is very confusing
  53    * so might change.)
  54    */
  55   playing_ok,
  56
  57   /** @brief Track is playing, but paused */
  58   playing_paused,
  59
  60   /** @brief Track is playing but the server is quitting */
  61   playing_quitting,
  62
  63   /** @brief Track was randomly chosen and has not been played
  64    *
  65    * This is going to become obsolete eventually; it's equivalent to @ref
  66    * playing_unplayed but for tracks with a different origin.
  67    */
  68   playing_random,
  69
  70   /** @brief Track was scratched */
  71   playing_scratched,
  72
  73   /** @brief Track is now playing
  74    *
  75    * This refers to the actual playing track, not something being decoded ahead
  76    * of time.
  77    */
  78   playing_started,
  79
  80   /** @brief Track has not been played yet */
  81   playing_unplayed
  82 };
  83
  84 extern const char *const playing_states[];
  85
  86 /** @brief Possible track origins
  87  *
  88  * This is a newly introduced field.  The aim is ultimately to separate the
  89  * concepts of the track origin and its current state.  NB that both are
  90  * potentially mutable!
  91  */
  92 enum track_origin {
  93   /** @brief Track was picked at random and then adopted by a user
  94    *
  95    * @c submitter identifies who adopted it.  This isn't implemented
  96    * yet.
  97    */
  98   origin_adopted,
  99
 100   /** @brief Track was picked by a user
 101    *
 102    * @c submitter identifies who picked it
 103    */
 104   origin_picked,
 105
 106   /** @brief Track was picked at random
 107    *
 108    * @c submitter will be NULL
 109    */
 110   origin_random,
 111
 112   /** @brief Track was scheduled by a user
 113    *
 114    * @c submitter identifies who picked it
 115    */
 116   origin_scheduled,
 117
 118   /** @brief Track is a scratch
 119    *
 120    * @c submitter identifies who did the scratching
 121    */
 122   origin_scratch
 123 };
 124
 125 extern const char *const track_origins[];
 126
 127 /** @brief One queue/recently played entry
 128  *
 129  * The queue and recently played list form a doubly linked list with the head
 130  * and tail referred to from @ref qhead and @ref phead.
 131  */
 132 struct queue_entry {
 133   /** @brief Next entry */
 134   struct queue_entry *next;
 135
 136   /** @brief Previous entry */
 137   struct queue_entry *prev;
 138
 139   /** @brief Path to track (a database key) */
 140   const char *track;
 141
 142   /** @brief Submitter or NULL
 143    *
 144    * Adopter, if @c origin is @ref origin_adopted.
 145    */
 146   const char *submitter;
 147
 148   /** @brief When submitted */
 149   time_t when;
 150
 151   /** @brief When played */
 152   time_t played;
 153
 154   /** @brief Current state
 155    *
 156    * Currently this includes some origin information but this is being phased
 157    * out. */
 158   enum playing_state state;
 159
 160   /** @brief Where track came from */
 161   enum track_origin origin;
 162
 163   /** @brief Wait status from player
 164    *
 165    * Only valid in certain states (TODO).
 166    */
 167   long wstat;
 168
 169   /** @brief Who scratched this track or NULL */
 170   const char *scratched;
 171
 172   /** @brief Unique ID string */
 173   const char *id;
 174
 175   /** @brief Estimated starting time */
 176   time_t expected;
 177
 178   /** @brief Type word from plugin (playing/buffered tracks only) */
 179   unsigned long type;                   /* type word from plugin */
 180
 181   /** @brief Plugin for this track (playing/buffered tracks only) */
 182   const struct plugin *pl;
 183
 184   /** @brief Player-specific data (playing/buffered tracks only) */
 185   void *data;
 186
 187   /** @brief How much of track has been played so far (seconds) */
 188   long sofar;
 189
 190   /** @brief True if decoder is connected to speaker */
 191   int prepared;
 192   /* For DISORDER_PLAYER_PAUSES only: */
 193
 194   /** @brief When last paused or 0 */
 195   time_t lastpaused;
 196
 197   /** @brief When last resumed or 0 */
 198   time_t lastresumed;
 199
 200   /** @brief How much of track was played up to last pause (seconds) */
 201   long uptopause;
 202
 203   /** @brief Owning queue (for Disobedience only) */
 204   struct queuelike *ql;
 205 };
 206
 207 void queue_insert_entry(struct queue_entry *b, struct queue_entry *n);
 208 void queue_delete_entry(struct queue_entry *node);
 209
 210 int queue_unmarshall(struct queue_entry *q, const char *s,
 211                      void (*error_handler)(const char *, void *),
 212                      void *u);
 213 /* unmarshall UTF-8 string @s@ into @q@ */
 214
 215 int queue_unmarshall_vec(struct queue_entry *q, int nvec, char **vec,
 216                      void (*error_handler)(const char *, void *),
 217                      void *u);
 218 /* unmarshall pre-split string @vec@ into @q@ */
 219
 220 char *queue_marshall(const struct queue_entry *q);
 221 /* marshall @q@ into a UTF-8 string */
 222
 223 #endif /* QUEUE_H */
 224
 225 /*
 226 Local Variables:
 227 c-basic-offset:2
 228 comment-column:40
 229 fill-column:79
 230 End:
 231 */