X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/e7eb3a2744aa45179daea235800753d3d1955338..5d22a5aeb435e90f20e5f8fd77c2256fd21d5f92:/lib/queue.h
diff --git a/lib/queue.h b/lib/queue.h
index ad70b34..72e3876 100644
--- a/lib/queue.h
+++ b/lib/queue.h
@@ -15,52 +15,204 @@
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
-
+/** @file lib/queue.h
+ * @brief Track queues
+ *
+ * Used for the queue, the recently played list and the currently playing
+ * track, both in the server and in clients.
+ */
#ifndef QUEUE_H
#define QUEUE_H
#include
-
+/** @brief Possible track states */
enum playing_state {
- playing_failed, /* failed to play */
- playing_isscratch, /* this is a scratch track */
- playing_no_player, /* couldn't find a player */
- playing_ok, /* played OK */
- playing_paused, /* started but paused */
- playing_quitting, /* interrupt because server quit */
- playing_random, /* unplayed randomly chosen track */
- playing_scratched, /* was scratched */
- playing_started, /* started to play */
- playing_unplayed /* haven't played this track yet */
+ /** @brief Track failed to play */
+ playing_failed,
+
+ /** @brief OBSOLETE
+ *
+ * Formerly denoted an unplayed scratch. This is now indicated by @p
+ * playing_unplayed and @p origin_scratch.
+ */
+ playing_isscratch,
+
+ /** @brief OBSOLETE
+ *
+ * Formerly meant that no player could be found. Nothing sets this any more.
+ */
+ playing_no_player,
+
+ /** @brief Play completed successfully
+ *
+ * Currently this actually means it finished decoding - it might still be
+ * buffered in the speaker, RTP player, sound card, etc.
+ *
+ * It might also mean that it's a (short!) track that hasn't been played at
+ * all yet but has been fully decoded ahead of time! (This is very confusing
+ * so might change.)
+ */
+ playing_ok,
+
+ /** @brief Track is playing, but paused */
+ playing_paused,
+
+ /** @brief Track is playing but the server is quitting */
+ playing_quitting,
+
+ /** @brief OBSOLETE
+ *
+ * Formerly this meant a track that was picked at random and has not yet been
+ * played. This situation is now indicated by @p playing_unplayed and @p
+ * origin_random (or @p origin_adopted).
+ */
+ playing_random,
+
+ /** @brief Track was scratched */
+ playing_scratched,
+
+ /** @brief Track is now playing
+ *
+ * This refers to the actual playing track, not something being decoded ahead
+ * of time.
+ */
+ playing_started,
+
+ /** @brief Track has not been played yet */
+ playing_unplayed
+};
+
+extern const char *const playing_states[];
+
+/** @brief Possible track origins
+ *
+ * This is a newly introduced field. The aim is ultimately to separate the
+ * concepts of the track origin and its current state. NB that both are
+ * potentially mutable!
+ */
+enum track_origin {
+ /** @brief Track was picked at random and then adopted by a user
+ *
+ * @c submitter identifies who adopted it.
+ */
+ origin_adopted,
+
+ /** @brief Track was picked by a user
+ *
+ * @c submitter identifies who picked it
+ */
+ origin_picked,
+
+ /** @brief Track was picked at random
+ *
+ * @c submitter will be NULL
+ */
+ origin_random,
+
+ /** @brief Track was scheduled by a user
+ *
+ * @c submitter identifies who picked it
+ */
+ origin_scheduled,
+
+ /** @brief Track is a scratch
+ *
+ * @c submitter identifies who did the scratching
+ */
+ origin_scratch
};
-extern const char *playing_states[];
+extern const char *const track_origins[];
-/* queue entries form a circular doubly-linked list */
+/** @brief One queue/recently played entry
+ *
+ * The queue and recently played list form a doubly linked list with the head
+ * and tail referred to from @ref qhead and @ref phead.
+ */
struct queue_entry {
- struct queue_entry *next; /* next entry */
- struct queue_entry *prev; /* previous entry */
- const char *track; /* path to track */
- const char *submitter; /* name of submitter */
- time_t when; /* time submitted */
- time_t played; /* when played */
- enum playing_state state; /* state */
- long wstat; /* wait status */
- const char *scratched; /* scratched by */
- const char *id; /* queue entry ID */
- time_t expected; /* expected started time */
- /* for playing or soon-to-be-played tracks only: */
+ /** @brief Next entry */
+ struct queue_entry *next;
+
+ /** @brief Previous entry */
+ struct queue_entry *prev;
+
+ /** @brief Path to track (a database key) */
+ const char *track;
+
+ /** @brief Submitter or NULL
+ *
+ * Adopter, if @c origin is @ref origin_adopted.
+ */
+ const char *submitter;
+
+ /** @brief When submitted */
+ time_t when;
+
+ /** @brief When played */
+ time_t played;
+
+ /** @brief Current state
+ *
+ * Currently this includes some origin information but this is being phased
+ * out. */
+ enum playing_state state;
+
+ /** @brief Where track came from */
+ enum track_origin origin;
+
+ /** @brief Wait status from player
+ *
+ * Only valid in certain states (TODO).
+ */
+ long wstat;
+
+ /** @brief Who scratched this track or NULL */
+ const char *scratched;
+
+ /** @brief Unique ID string */
+ const char *id;
+
+ /** @brief Estimated starting time */
+ time_t expected;
+
+ /** @brief Type word from plugin (playing/buffered tracks only) */
unsigned long type; /* type word from plugin */
- const struct plugin *pl; /* plugin that's playing this track */
- void *data; /* player data */
- long sofar; /* how much played so far */
- int prepared; /* true when connected to speaker */
+
+ /** @brief Plugin for this track (playing/buffered tracks only) */
+ const struct plugin *pl;
+
+ /** @brief Player-specific data (playing/buffered tracks only) */
+ void *data;
+
+ /** @brief How much of track has been played so far (seconds) */
+ long sofar;
+
+ /** @brief True if decoder is connected to speaker
+ *
+ * This is not a @ref playing_state for a couple of reasons
+ * - it is orthogonal to @ref playing_started and @ref playing_unplayed
+ * - it would have to be hidden to other users of @c queue_entry
+ *
+ * For non-raw tracks this should always be zero.
+ */
+ int prepared;
/* For DISORDER_PLAYER_PAUSES only: */
- time_t lastpaused, lastresumed; /* when last paused/resumed, or 0 */
- long uptopause; /* how much played up to last pause */
- /* For Disobedience */
- struct queuelike *ql; /* owning queue */
+
+ /** @brief When last paused or 0 */
+ time_t lastpaused;
+
+ /** @brief When last resumed or 0 */
+ time_t lastresumed;
+
+ /** @brief How much of track was played up to last pause (seconds) */
+ long uptopause;
+
+ /** @brief Owning queue (for Disobedience only) */
+ struct queuelike *ql;
+
+ /** @brief Decoder (or player) process ID */
+ pid_t pid;
};
void queue_insert_entry(struct queue_entry *b, struct queue_entry *n);