ocarina/include/core/queue.h

/*
 * Copyright 2013 (c) Anna Schumaker.
 *
 * Queues are lists of tracks that the user has requested to play next.
 * Users of queues are expected to implement their own save and load functions,
 * and to provide a filled out queue_ops structure during initialization.
 */
#ifndef OCARINA_CORE_QUEUE_H
#define OCARINA_CORE_QUEUE_H

#include <core/containers/queue.h>
#include <core/file.h>
#include <core/tags/track.h>

struct queue;


enum queue_flags {
	Q_ENABLED    = (1 << 0), /* Queue is enabled.                        */
	Q_RANDOM     = (1 << 1), /* Queue will pick songs randomly.          */
	Q_REPEAT     = (1 << 2), /* Queue will not remove songs when picked. */
	Q_NO_SORT    = (1 << 3), /* Queue will not be sorted.                */
	Q_SAVE_FLAGS = (1 << 4), /* Queue will be saved when flags change.   */
	Q_SAVE_SORT  = (1 << 5), /* Queue will be saved when sorted.         */
	Q_ADD_FRONT  = (1 << 6), /* Queue will add new tracks at the front.  */
};


struct queue_ops {
	/* Called to tell a higher layer that a track has been added. */
	void (*qop_added)(struct queue *, unsigned int);

	/* Called to tell a higher layer that a track has been removed. */
	void (*qop_removed)(struct queue *, unsigned int);

	/* Called to tell a higher layer that the queue has been cleared. */
	void (*qop_cleared)(struct queue *, unsigned int);

	/* Called to have a higher layer save the queue. */
	void (*qop_save)(struct queue *, enum queue_flags);

	/* Called to hell a higher layer that a track has been updated. */
	void (*qop_updated)(struct queue *, unsigned int);
};


struct queue {
	unsigned int   q_flags;  /* The queue's set of flags.               */
	unsigned int   q_length; /* The queue's total runtime (in seconds). */
	struct _queue  q_tracks; /* The queue's list of tracks.             */
	struct _q_iter q_cur;    /* The queue's last-played position.       */
	GSList        *q_sort;   /* The queue's sort order.                 */

	const struct queue_ops *q_ops; /* The queue's operations vector. */
};


/* Called to initialize a queue. */
void queue_init(struct queue *, unsigned int, const struct queue_ops *);

/* Called to deinitialize a queue. */
void queue_deinit(struct queue *);


/* Called to set a queue flag. */
void queue_set_flag(struct queue *, enum queue_flags);

/* Called to clear a queue flag. */
void queue_unset_flag(struct queue *, enum queue_flags);

/* Called to check if the queue has a specific flag set. */
static inline bool queue_has_flag(struct queue *queue, enum queue_flags flag)
{
	return (queue->q_flags & flag) == (unsigned int)flag;
}

/* Called to find the size of the queue. */
static inline unsigned int queue_size(struct queue *queue)
{
	return _q_size(&queue->q_tracks);
}

/* Called to access the queued track at a given index. */
static inline struct track *queue_at(struct queue *queue, unsigned int index)
{
	return (struct track *)g_queue_peek_nth(&queue->q_tracks._queue, index);
}


/* Called to add a track to the queue. */
unsigned int queue_add(struct queue *, struct track *);

/* Called to remove a track from the queue by index. */
void queue_remove(struct queue *, unsigned int);

/* Called to remove all instances of the track from the queue. */
void queue_remove_all(struct queue *, struct track *);

/* Called to remove all tracks from the queue. */
void queue_clear(struct queue *);

/* Called to tell the queue that a track has been updated. */
void queue_updated(struct queue *, struct track *);


/* Called to tell the queue that a specific index has been selected. */
struct track *queue_selected(struct queue *, unsigned int);

/* Called to pick the next track from the queue. */
struct track *queue_next(struct queue *);

/* Called to sort the queue without changing sort order. */
void queue_resort(struct queue *);

/* Called to change the sort order and resort the queue. */
void queue_sort(struct queue *, enum compare_t, bool);

#endif /* OCARINA_CORE_QUEUE_H */