/* $Id: cddb_disc.h,v 1.22 2007/08/07 03:12:53 jcaratzas Exp $ Copyright (C) 2003, 2004, 2005 Kris Verbeeck This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef CDDB_DISC_H #define CDDB_DISC_H 1 #ifdef __cplusplus extern "C" { #endif #include /** * The number of frames that fit into one second. */ #define FRAMES_PER_SECOND 75 /** * This macro converts an amount of frames into an amount of seconds. */ #define FRAMES_TO_SECONDS(f) ((f) / FRAMES_PER_SECOND) /** * This macro converts an amount of seconds into an amount of frames. */ #define SECONDS_TO_FRAMES(s) ((s) * FRAMES_PER_SECOND) /** * The different CDDB categories. */ typedef enum { CDDB_CAT_DATA = 0, /**< data disc */ CDDB_CAT_FOLK, /**< folk music */ CDDB_CAT_JAZZ, /**< jazz music */ CDDB_CAT_MISC, /**< miscellaneous, use if no other category matches */ CDDB_CAT_ROCK, /**< rock and pop music */ CDDB_CAT_COUNTRY, /**< country music */ CDDB_CAT_BLUES, /**< blues music */ CDDB_CAT_NEWAGE, /**< new age music */ CDDB_CAT_REGGAE, /**< reggae music */ CDDB_CAT_CLASSICAL, /**< classical music */ CDDB_CAT_SOUNDTRACK, /**< soundtracks */ CDDB_CAT_INVALID, /**< (internal) invalid category */ CDDB_CAT_LAST /**< (internal) category counter */ } cddb_cat_t; /** * String values for the CDDB categories. */ extern const char *CDDB_CATEGORY[CDDB_CAT_LAST]; /** * The CDDB disc structure. Contains all information associated with * a full CD. */ typedef struct cddb_disc_s cddb_disc_t; /* --- construction / destruction */ /** * Creates a new CDDB disc structure. * * @return The CDDB disc structure or NULL if memory allocation failed. */ cddb_disc_t *cddb_disc_new(void); /** * Free all resources associated with the given CDDB disc structure. * The tracks will also be freed automatically. * * @param disc The CDDB disc structure. */ void cddb_disc_destroy(cddb_disc_t *disc); /** * Creates a clone of the given disc. * * @param disc The CDDB disc structure. */ cddb_disc_t *cddb_disc_clone(const cddb_disc_t *disc); /* --- track manipulation */ /** * Add a new track to a disc. The track is added to the end of the * existing list of tracks. * * @param disc The CDDB disc structure. * @param track The CDDB track structure. */ void cddb_disc_add_track(cddb_disc_t *disc, cddb_track_t *track); /** * Retrieves a numbered track from the disc. If there is no track * with the given number, then NULL will be returned. * * @param disc The CDDB disc structure. * @param track_no The track number; starting at 0. */ cddb_track_t *cddb_disc_get_track(const cddb_disc_t *disc, int track_no); /** * Returns the first track of the disc. If there is no such track * then NULL will be returned. The internal track iterator will also * be reset. This function should be called before the first call to * cddb_disc_get_track_next. * * @see cddb_disc_get_track_next * * @param disc The CDDB disc structure. */ cddb_track_t *cddb_disc_get_track_first(cddb_disc_t *disc); /** * Returns the next track on the disc and advances the internal track * iterator. If there is no such track then NULL will be returned. * This function should be called after calling * cddb_disc_get_track_first. * * @see cddb_disc_get_track_first * * @param disc The CDDB disc structure. */ cddb_track_t *cddb_disc_get_track_next(cddb_disc_t *disc); /* --- setters / getters --- */ /** * Get the ID of the disc. If the disc is invalid or the disc ID is * not yet initialized 0 will be returned. * * @param disc The CDDB disc structure. */ unsigned int cddb_disc_get_discid(const cddb_disc_t *disc); /** * Set the ID of the disc. When the disc ID is not known yet, then it * can be calculated with the cddb_disc_calc_discid function (which * will automatically initialize the correct field in the disc * structure). * * @see cddb_disc_calc_discid * * @param disc The CDDB disc structure. * @param id The disc ID. */ void cddb_disc_set_discid(cddb_disc_t *disc, unsigned int id); /** * Get the disc CDDB category ID. If the disc is invalid or no * category is set then CDDB_CAT_INVALID will be returned. If you * want a string representation of the category use the * cddb_disc_get_category_str function. * * @see cddb_disc_set_category * @see cddb_disc_get_category_str * @see cddb_disc_set_category_str * @see cddb_cat_t * @see CDDB_CATEGORY * * @param disc The CDDB disc structure. * @return The CDDB category ID. */ cddb_cat_t cddb_disc_get_category(const cddb_disc_t *disc); /** * Set the disc CDDB category ID. * * @see cddb_disc_get_category * @see cddb_disc_get_category_str * @see cddb_disc_set_category_str * @see cddb_cat_t * @see CDDB_CATEGORY * * @param disc The CDDB disc structure. * @param cat The CDDB category ID. */ void cddb_disc_set_category(cddb_disc_t *disc, cddb_cat_t cat); /** * Get the disc CDDB category as a string. If no category is set for * this disc then 'invalid' will be returned. If the disc structure * is invalid NULL is returned. If you only want the ID of the * category use the cddb_disc_get_category function. * * @see cddb_disc_get_category * @see cddb_disc_set_category * @see cddb_disc_set_category_str * * @param disc The CDDB disc structure. * @return The CDDB category ID. */ const char *cddb_disc_get_category_str(cddb_disc_t *disc); /** * Sets the category of the disc. If the specified category is * an invalid CDDB category, then CDDB_CAT_MISC will be used. * * @see cddb_disc_get_category * @see cddb_disc_set_category * @see cddb_disc_get_category_str * @see CDDB_CATEGORY * * @param disc The CDDB disc structure. * @param cat The category string. */ void cddb_disc_set_category_str(cddb_disc_t *disc, const char *cat); /** * Get the disc genre. If no genre is set for this disc then NULL * will be returned. As opposed to the disc category, this field is * not limited to a predefined set. * * @param disc The CDDB disc structure. * @return The disc genre. */ const char *cddb_disc_get_genre(const cddb_disc_t *disc); /** * Set the disc genre. As opposed to the disc category, this field is * not limited to a predefined set. If the disc already had a genre, * then the memory for that string will be freed. The new genre will * be copied into a new chunk of memory. * * @see cddb_disc_get_category_str * * @param disc The CDDB disc structure. * @param genre The disc genre. */ void cddb_disc_set_genre(cddb_disc_t *disc, const char *genre); /** * Get the disc length. If no length is set for this disc then 0 will * be returned. * * @param disc The CDDB disc structure. * @return The disc length in seconds. */ unsigned int cddb_disc_get_length(const cddb_disc_t *disc); /** * Set the disc length. * * @param disc The CDDB disc structure. * @param l The disc length in seconds. */ void cddb_disc_set_length(cddb_disc_t *disc, unsigned int l); /** * Get the revision number of the disc. * * @param disc The CDDB disc structure. */ unsigned int cddb_disc_get_revision(const cddb_disc_t *disc); /** * Set the revision number of the disc. * * @param disc The CDDB disc structure. * @param rev The revision number. */ void cddb_disc_set_revision(cddb_disc_t *disc, unsigned int rev); /** * Get the year of publication for this disc. If no year is defined 0 * is returned. * * @param disc The CDDB disc structure. * @return The disc year. */ unsigned int cddb_disc_get_year(const cddb_disc_t *disc); /** * Set the year of publication for this disc. * * @param disc The CDDB disc structure. * @param y The disc year. */ void cddb_disc_set_year(cddb_disc_t *disc, unsigned int y); /** * Get the number of tracks on the disc. If the disc is invalid -1 is * returned. * * @param disc The CDDB disc structure. * @return The number of tracks. */ int cddb_disc_get_track_count(const cddb_disc_t *disc); /** * Get the disc title. If the disc is invalid or no title is set then * NULL will be returned. * * @param disc The CDDB disc structure. * @return The disc title. */ const char *cddb_disc_get_title(const cddb_disc_t *disc); /** * Set the disc title. If the disc already had a title, then the * memory for that string will be freed. The new title will be copied * into a new chunk of memory. If the given title is NULL, then the * title of the disc will be deleted. * * @param disc The CDDB disc structure. * @param title The new disc title. */ void cddb_disc_set_title(cddb_disc_t *disc, const char *title); /** * Append to the disc title. If the disc does not have a title yet, * then a new one will be created from the given string, otherwise * that string will be appended to the existing title. * * @param disc The CDDB disc structure. * @param title Part of the disc title. */ void cddb_disc_append_title(cddb_disc_t *disc, const char *title); /** * Get the disc artist name. If the disc is invalid or no artist is * set then NULL will be returned. * * @param disc The CDDB disc structure. * @return The disc artist name. */ const char *cddb_disc_get_artist(const cddb_disc_t *disc); /** * Set the disc artist name. If the disc already had an artist name, * then the memory for that string will be freed. The new artist name * will be copied into a new chunk of memory. If the given artist * name is NULL, then the artist name of the disc will be deleted. * * @param disc The CDDB disc structure. * @param artist The new disc artist name. */ void cddb_disc_set_artist(cddb_disc_t *disc, const char *artist); /** * Append to the disc artist. If the disc does not have an artist * yet, then a new one will be created from the given string, * otherwise that string will be appended to the existing artist. * * @param disc The CDDB disc structure. * @param artist Part of the artist name. */ void cddb_disc_append_artist(cddb_disc_t *disc, const char *artist); /** * Get the extended disc data. If the disc is invalid or no extended * data is set then NULL will be returned. * * @param disc The CDDB disc structure. * @return The extended data. */ const char *cddb_disc_get_ext_data(const cddb_disc_t *disc); /** * Set the extended data for the disc. If the disc already had * extended data, then the memory for that string will be freed. The * new extended data will be copied into a new chunk of memory. If * the given extended data is NULL, then the existing data will be * deleted. * * @param disc The CDDB disc structure. * @param ext_data The new extended data. */ void cddb_disc_set_ext_data(cddb_disc_t *disc, const char *ext_data); /** * Append to the extended disc data. If the disc does not have an * extended data section yet, then a new one will be created from the * given string, otherwise that string will be appended to the * existing data. * * @param disc The CDDB disc structure. * @param ext_data Part of the extended disc data. */ void cddb_disc_append_ext_data(cddb_disc_t *disc, const char *ext_data); /* --- miscellaneous */ /** * Copy all data from one disc to another. Any fields that are * unavailable in the source disc structure will not result in a reset * of the same field in the destination disc structure; e.g. if there * is no title in the source disc, but there is one in the destination * disc, then the destination's title will remain unchanged. * * @param dst The destination CDDB disc structure. * @param src The source CDDB disc structure. */ void cddb_disc_copy(cddb_disc_t *dst, cddb_disc_t *src); /** * Calculate the CDDB disc ID. To calculate a disc ID the provided * disc needs to have its length set, and every track in the disc * structure needs to have its frame offset initialized. The disc ID * field will be set in the disc structure. * * @param disc The CDDB disc structure. * @return A non-zero value if the calculation succeeded, zero * otherwise. */ int cddb_disc_calc_discid(cddb_disc_t *disc); /** * Prints information about the disc on stdout. This is just a * debugging routine to display the structure's content. * * @param disc The CDDB disc structure. */ void cddb_disc_print(cddb_disc_t *disc); #ifdef __cplusplus } #endif #endif /* CDDB_DISC_H */