ocarina/include/core/tags/track.h

/**
 * Copyright 2014 (c) Anna Schumaker.
 */
#ifndef OCARINA_CORE_TAGS_TRACK_H
#define OCARINA_CORE_TAGS_TRACK_H

extern "C" {
#include <core/date.h>
}
#include <core/tags/generic.h>
#include <core/tags/artist.h>
#include <core/tags/album.h>
#include <core/tags/genre.h>
#include <core/tags/library.h>


/**
 * The Track tag is used to store information about tracks that
 * have been added to the tag database.
 */
struct track : public GenericTag {
	struct album   *tr_album;   /* This track's associated album.   */
	struct artist  *tr_artist;  /* This track's associated artist.  */
	struct genre   *tr_genre;   /* This track's associated genre.   */
	struct library *tr_library; /* This track's associated library. */

	unsigned int tr_count;  /* This track's play count.         */
	unsigned int tr_length; /* This track's length, in seconds. */
	unsigned int tr_track;  /* This track's track number.       */

	struct date tr_date; /* This track's last-played date.              */
	std::string tr_path; /* This track's path, relative to the library. */

	/**
	 * Track constructor
	 *
	 * @param  album    The album containing this track.
	 * @param  artist   The artist performing this track.
	 * @param  genre    The genre describing this track.
	 * @param  library  The library containing this track.
	 * @param  filepath The path of this track, relative to the library root.
	 * @param  name     The name (title) of this track.
	 * @param  length   The length of this track (in seconds).
	 * @param  track    The track number of this track.
	 */
	track(struct album *, struct artist *, struct genre *, struct library *,
	      const std::string &, const std::string &, unsigned int,
	      unsigned int);

	/**
	 * Track copy constructor
	 *
	 * @param track  The Track tag that should be copied.
	 */
	track(const struct track &);

	track();  /**< Track constructor. */
	~track(); /**< Track destructor.  */


	struct album   *album();   /**< @return Track::_album.   */
	struct artist  *artist();  /**< @return Track::_artist.  */
	struct genre   *genre();   /**< @return Track::_genre.   */
	struct library *library(); /**< @return Track::_library. */

	unsigned int count();  /**< @return Track::_count.  */
	unsigned int length(); /**< @return Track::_length. */
	unsigned int track_nr();  /**< @return Track::_track.  */


	/**
	 * @return A locale-dependent string containing the day this
	 *         track was last played, or "Never" if the track has
	 *         never been played.
	 */
	const std::string date() const;

	/** @return The full path of this track. */
	const std::string path() const;

	/**
	 * A track's primary key is the concatenation of the library index
	 * and the relative path.
	 *
	 * @return Track::_library->index() / Track::_path.
	 */
	const std::string primary_key() const;

	/** Increment Track::_count and set Track::_date to today's date. */
	void played();

	/**
	 * Compare two tracks based on last played date.
	 *
	 * @param  rhs  The other track to compare.
	 * @return < 0: lhs < rhs.
	 * @return   0: lhs == rhs.
	 * @return > 0: lhs > rhs;
	 */
	int compare_date(const struct track *);


	/**
	 * Read track data from file.
	 *
	 * @param  file  The file to read from.
	 */
	void read(file &);

	/**
	 * Write track data to file.
	 *
	 * @param  file  The file to write to.
	 */
	void write(file &);
};

namespace tags
{
	/** Called to read the track_db from disk. */
	void init_track_db();

	/**
	 * Called to create a new Track tag.
	 *
	 * @param  album    The album containing this track.
	 * @param  artist   The artist performing this track.
	 * @param  genre    The genre describing this track.
	 * @param  library  The library containing this track.
	 * @param  filepath The path of this track, relative to the library root.
	 * @param  name     The name (title) of this track.
	 * @param  length   The length of this track (in seconds).
	 * @param  track    The track number of this track.
	 * @return A new Track tag, or NULL if this Track is already in
	 *         the track_db.
	 */
	struct track *add_track(struct album *, struct artist *, struct genre *,
			 struct library *, const std::string &,
			 const std::string &, unsigned int, unsigned int);

	/**
	 * Called to look up a Track tag by tag index.
	 *
	 * @param  index  The index of the Track tag.
	 * @return A matching Track tag, or NULL.
	 */
	struct track *get_track(const unsigned int);

	/**
	 * Called to remove a Track tag from the database.
	 *
	 * @param  track  The Track tag to be removed.
	 */
	void remove_track(struct track *);

	/**
	 * Called to remove all tracks associated with a specific Library.
	 *
	 * @param  library  The Library tag that will be matched.
	 */
	void remove_library_tracks(struct library *);

	/**
	 * Called to find the number of rows in the track_db,
	 * including NULL rows.
	 *
	 * @return The Database::actual_size() of the track_db.
	 */
	unsigned int track_size();

	/** Called to write the track_db to disk. */
	void commit_track_db();
}

#endif /* OCARINA_CORE_TAGS_TRACK_H */