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