diff options
Diffstat (limited to 'include/cddb/cddb_disc.h')
| -rw-r--r-- | include/cddb/cddb_disc.h | 450 |
1 files changed, 450 insertions, 0 deletions
diff --git a/include/cddb/cddb_disc.h b/include/cddb/cddb_disc.h new file mode 100644 index 00000000..7951ae96 --- /dev/null +++ b/include/cddb/cddb_disc.h @@ -0,0 +1,450 @@ +/* + $Id: cddb_disc.h,v 1.22 2007/08/07 03:12:53 jcaratzas Exp $ + + Copyright (C) 2003, 2004, 2005 Kris Verbeeck <airborne@advalvas.be> + + 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 <cddb/cddb_track.h> + + +/** + * 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 */ |