#include <time.h>
-
+/** @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 Could not find a player
+ *
+ * Obsolete - 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[];
enum track_origin {
/** @brief Track was picked at random and then adopted by a user
*
- * @c submitter identifies who adopted it. This isn't implemented
- * yet.
+ * @c submitter identifies who adopted it.
*/
origin_adopted,
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 */
- enum track_origin origin; /* where track came from */
- 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 */
+ 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;
};
void queue_insert_entry(struct queue_entry *b, struct queue_entry *n);
~mdw / disorder / blobdiff