1 /* 2 $Id: cddb_disc.h,v 1.22 2007/08/07 03:12:53 jcaratzas Exp $ 3 4 Copyright (C) 2003, 2004, 2005 Kris Verbeeck <airborne@advalvas.be> 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License as published by the Free Software Foundation; either 9 version 2 of the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Library General Public License for more details. 15 16 You should have received a copy of the GNU Library General Public 17 License along with this library; if not, write to the 18 Free Software Foundation, Inc., 59 Temple Place - Suite 330, 19 Boston, MA 02111-1307, USA. 20 */ 21 22 #ifndef CDDB_DISC_H 23 #define CDDB_DISC_H 1 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 30 #include <cddb/cddb_track.h> 31 32 33 /** 34 * The number of frames that fit into one second. 35 */ 36 #define FRAMES_PER_SECOND 75 37 38 /** 39 * This macro converts an amount of frames into an amount of seconds. 40 */ 41 #define FRAMES_TO_SECONDS(f) ((f) / FRAMES_PER_SECOND) 42 43 /** 44 * This macro converts an amount of seconds into an amount of frames. 45 */ 46 #define SECONDS_TO_FRAMES(s) ((s) * FRAMES_PER_SECOND) 47 48 /** 49 * The different CDDB categories. 50 */ 51 typedef enum { 52 CDDB_CAT_DATA = 0, /**< data disc */ 53 CDDB_CAT_FOLK, /**< folk music */ 54 CDDB_CAT_JAZZ, /**< jazz music */ 55 CDDB_CAT_MISC, /**< miscellaneous, use if no other 56 category matches */ 57 CDDB_CAT_ROCK, /**< rock and pop music */ 58 CDDB_CAT_COUNTRY, /**< country music */ 59 CDDB_CAT_BLUES, /**< blues music */ 60 CDDB_CAT_NEWAGE, /**< new age music */ 61 CDDB_CAT_REGGAE, /**< reggae music */ 62 CDDB_CAT_CLASSICAL, /**< classical music */ 63 CDDB_CAT_SOUNDTRACK, /**< soundtracks */ 64 CDDB_CAT_INVALID, /**< (internal) invalid category */ 65 CDDB_CAT_LAST /**< (internal) category counter */ 66 } cddb_cat_t; 67 68 /** 69 * String values for the CDDB categories. 70 */ 71 extern const char *CDDB_CATEGORY[CDDB_CAT_LAST]; 72 73 /** 74 * The CDDB disc structure. Contains all information associated with 75 * a full CD. 76 */ 77 typedef struct cddb_disc_s cddb_disc_t; 78 79 80 /* --- construction / destruction */ 81 82 83 /** 84 * Creates a new CDDB disc structure. 85 * 86 * @return The CDDB disc structure or NULL if memory allocation failed. 87 */ 88 cddb_disc_t *cddb_disc_new(void); 89 90 /** 91 * Free all resources associated with the given CDDB disc structure. 92 * The tracks will also be freed automatically. 93 * 94 * @param disc The CDDB disc structure. 95 */ 96 void cddb_disc_destroy(cddb_disc_t *disc); 97 98 /** 99 * Creates a clone of the given disc. 100 * 101 * @param disc The CDDB disc structure. 102 */ 103 cddb_disc_t *cddb_disc_clone(const cddb_disc_t *disc); 104 105 106 /* --- track manipulation */ 107 108 109 /** 110 * Add a new track to a disc. The track is added to the end of the 111 * existing list of tracks. 112 * 113 * @param disc The CDDB disc structure. 114 * @param track The CDDB track structure. 115 */ 116 void cddb_disc_add_track(cddb_disc_t *disc, cddb_track_t *track); 117 118 /** 119 * Retrieves a numbered track from the disc. If there is no track 120 * with the given number, then NULL will be returned. 121 * 122 * @param disc The CDDB disc structure. 123 * @param track_no The track number; starting at 0. 124 */ 125 cddb_track_t *cddb_disc_get_track(const cddb_disc_t *disc, int track_no); 126 127 /** 128 * Returns the first track of the disc. If there is no such track 129 * then NULL will be returned. The internal track iterator will also 130 * be reset. This function should be called before the first call to 131 * cddb_disc_get_track_next. 132 * 133 * @see cddb_disc_get_track_next 134 * 135 * @param disc The CDDB disc structure. 136 */ 137 cddb_track_t *cddb_disc_get_track_first(cddb_disc_t *disc); 138 139 /** 140 * Returns the next track on the disc and advances the internal track 141 * iterator. If there is no such track then NULL will be returned. 142 * This function should be called after calling 143 * cddb_disc_get_track_first. 144 * 145 * @see cddb_disc_get_track_first 146 * 147 * @param disc The CDDB disc structure. 148 */ 149 cddb_track_t *cddb_disc_get_track_next(cddb_disc_t *disc); 150 151 152 /* --- setters / getters --- */ 153 154 155 /** 156 * Get the ID of the disc. If the disc is invalid or the disc ID is 157 * not yet initialized 0 will be returned. 158 * 159 * @param disc The CDDB disc structure. 160 */ 161 unsigned int cddb_disc_get_discid(const cddb_disc_t *disc); 162 163 /** 164 * Set the ID of the disc. When the disc ID is not known yet, then it 165 * can be calculated with the cddb_disc_calc_discid function (which 166 * will automatically initialize the correct field in the disc 167 * structure). 168 * 169 * @see cddb_disc_calc_discid 170 * 171 * @param disc The CDDB disc structure. 172 * @param id The disc ID. 173 */ 174 void cddb_disc_set_discid(cddb_disc_t *disc, unsigned int id); 175 176 /** 177 * Get the disc CDDB category ID. If the disc is invalid or no 178 * category is set then CDDB_CAT_INVALID will be returned. If you 179 * want a string representation of the category use the 180 * cddb_disc_get_category_str function. 181 * 182 * @see cddb_disc_set_category 183 * @see cddb_disc_get_category_str 184 * @see cddb_disc_set_category_str 185 * @see cddb_cat_t 186 * @see CDDB_CATEGORY 187 * 188 * @param disc The CDDB disc structure. 189 * @return The CDDB category ID. 190 */ 191 cddb_cat_t cddb_disc_get_category(const cddb_disc_t *disc); 192 193 /** 194 * Set the disc CDDB category ID. 195 * 196 * @see cddb_disc_get_category 197 * @see cddb_disc_get_category_str 198 * @see cddb_disc_set_category_str 199 * @see cddb_cat_t 200 * @see CDDB_CATEGORY 201 * 202 * @param disc The CDDB disc structure. 203 * @param cat The CDDB category ID. 204 */ 205 void cddb_disc_set_category(cddb_disc_t *disc, cddb_cat_t cat); 206 207 /** 208 * Get the disc CDDB category as a string. If no category is set for 209 * this disc then 'invalid' will be returned. If the disc structure 210 * is invalid NULL is returned. If you only want the ID of the 211 * category use the cddb_disc_get_category function. 212 * 213 * @see cddb_disc_get_category 214 * @see cddb_disc_set_category 215 * @see cddb_disc_set_category_str 216 * 217 * @param disc The CDDB disc structure. 218 * @return The CDDB category ID. 219 */ 220 const char *cddb_disc_get_category_str(cddb_disc_t *disc); 221 222 /** 223 * Sets the category of the disc. If the specified category is 224 * an invalid CDDB category, then CDDB_CAT_MISC will be used. 225 * 226 * @see cddb_disc_get_category 227 * @see cddb_disc_set_category 228 * @see cddb_disc_get_category_str 229 * @see CDDB_CATEGORY 230 * 231 * @param disc The CDDB disc structure. 232 * @param cat The category string. 233 */ 234 void cddb_disc_set_category_str(cddb_disc_t *disc, const char *cat); 235 236 /** 237 * Get the disc genre. If no genre is set for this disc then NULL 238 * will be returned. As opposed to the disc category, this field is 239 * not limited to a predefined set. 240 * 241 * @param disc The CDDB disc structure. 242 * @return The disc genre. 243 */ 244 const char *cddb_disc_get_genre(const cddb_disc_t *disc); 245 246 /** 247 * Set the disc genre. As opposed to the disc category, this field is 248 * not limited to a predefined set. If the disc already had a genre, 249 * then the memory for that string will be freed. The new genre will 250 * be copied into a new chunk of memory. 251 * 252 * @see cddb_disc_get_category_str 253 * 254 * @param disc The CDDB disc structure. 255 * @param genre The disc genre. 256 */ 257 void cddb_disc_set_genre(cddb_disc_t *disc, const char *genre); 258 259 /** 260 * Get the disc length. If no length is set for this disc then 0 will 261 * be returned. 262 * 263 * @param disc The CDDB disc structure. 264 * @return The disc length in seconds. 265 */ 266 unsigned int cddb_disc_get_length(const cddb_disc_t *disc); 267 268 /** 269 * Set the disc length. 270 * 271 * @param disc The CDDB disc structure. 272 * @param l The disc length in seconds. 273 */ 274 void cddb_disc_set_length(cddb_disc_t *disc, unsigned int l); 275 276 /** 277 * Get the revision number of the disc. 278 * 279 * @param disc The CDDB disc structure. 280 */ 281 unsigned int cddb_disc_get_revision(const cddb_disc_t *disc); 282 283 /** 284 * Set the revision number of the disc. 285 * 286 * @param disc The CDDB disc structure. 287 * @param rev The revision number. 288 */ 289 void cddb_disc_set_revision(cddb_disc_t *disc, unsigned int rev); 290 291 /** 292 * Get the year of publication for this disc. If no year is defined 0 293 * is returned. 294 * 295 * @param disc The CDDB disc structure. 296 * @return The disc year. 297 */ 298 unsigned int cddb_disc_get_year(const cddb_disc_t *disc); 299 300 /** 301 * Set the year of publication for this disc. 302 * 303 * @param disc The CDDB disc structure. 304 * @param y The disc year. 305 */ 306 void cddb_disc_set_year(cddb_disc_t *disc, unsigned int y); 307 308 /** 309 * Get the number of tracks on the disc. If the disc is invalid -1 is 310 * returned. 311 * 312 * @param disc The CDDB disc structure. 313 * @return The number of tracks. 314 */ 315 int cddb_disc_get_track_count(const cddb_disc_t *disc); 316 317 /** 318 * Get the disc title. If the disc is invalid or no title is set then 319 * NULL will be returned. 320 * 321 * @param disc The CDDB disc structure. 322 * @return The disc title. 323 */ 324 const char *cddb_disc_get_title(const cddb_disc_t *disc); 325 326 /** 327 * Set the disc title. If the disc already had a title, then the 328 * memory for that string will be freed. The new title will be copied 329 * into a new chunk of memory. If the given title is NULL, then the 330 * title of the disc will be deleted. 331 * 332 * @param disc The CDDB disc structure. 333 * @param title The new disc title. 334 */ 335 void cddb_disc_set_title(cddb_disc_t *disc, const char *title); 336 337 /** 338 * Append to the disc title. If the disc does not have a title yet, 339 * then a new one will be created from the given string, otherwise 340 * that string will be appended to the existing title. 341 * 342 * @param disc The CDDB disc structure. 343 * @param title Part of the disc title. 344 */ 345 void cddb_disc_append_title(cddb_disc_t *disc, const char *title); 346 347 /** 348 * Get the disc artist name. If the disc is invalid or no artist is 349 * set then NULL will be returned. 350 * 351 * @param disc The CDDB disc structure. 352 * @return The disc artist name. 353 */ 354 const char *cddb_disc_get_artist(const cddb_disc_t *disc); 355 356 /** 357 * Set the disc artist name. If the disc already had an artist name, 358 * then the memory for that string will be freed. The new artist name 359 * will be copied into a new chunk of memory. If the given artist 360 * name is NULL, then the artist name of the disc will be deleted. 361 * 362 * @param disc The CDDB disc structure. 363 * @param artist The new disc artist name. 364 */ 365 void cddb_disc_set_artist(cddb_disc_t *disc, const char *artist); 366 367 /** 368 * Append to the disc artist. If the disc does not have an artist 369 * yet, then a new one will be created from the given string, 370 * otherwise that string will be appended to the existing artist. 371 * 372 * @param disc The CDDB disc structure. 373 * @param artist Part of the artist name. 374 */ 375 void cddb_disc_append_artist(cddb_disc_t *disc, const char *artist); 376 377 /** 378 * Get the extended disc data. If the disc is invalid or no extended 379 * data is set then NULL will be returned. 380 * 381 * @param disc The CDDB disc structure. 382 * @return The extended data. 383 */ 384 const char *cddb_disc_get_ext_data(const cddb_disc_t *disc); 385 386 /** 387 * Set the extended data for the disc. If the disc already had 388 * extended data, then the memory for that string will be freed. The 389 * new extended data will be copied into a new chunk of memory. If 390 * the given extended data is NULL, then the existing data will be 391 * deleted. 392 * 393 * @param disc The CDDB disc structure. 394 * @param ext_data The new extended data. 395 */ 396 void cddb_disc_set_ext_data(cddb_disc_t *disc, const char *ext_data); 397 398 /** 399 * Append to the extended disc data. If the disc does not have an 400 * extended data section yet, then a new one will be created from the 401 * given string, otherwise that string will be appended to the 402 * existing data. 403 * 404 * @param disc The CDDB disc structure. 405 * @param ext_data Part of the extended disc data. 406 */ 407 void cddb_disc_append_ext_data(cddb_disc_t *disc, const char *ext_data); 408 409 410 /* --- miscellaneous */ 411 412 413 /** 414 * Copy all data from one disc to another. Any fields that are 415 * unavailable in the source disc structure will not result in a reset 416 * of the same field in the destination disc structure; e.g. if there 417 * is no title in the source disc, but there is one in the destination 418 * disc, then the destination's title will remain unchanged. 419 * 420 * @param dst The destination CDDB disc structure. 421 * @param src The source CDDB disc structure. 422 */ 423 void cddb_disc_copy(cddb_disc_t *dst, cddb_disc_t *src); 424 425 /** 426 * Calculate the CDDB disc ID. To calculate a disc ID the provided 427 * disc needs to have its length set, and every track in the disc 428 * structure needs to have its frame offset initialized. The disc ID 429 * field will be set in the disc structure. 430 * 431 * @param disc The CDDB disc structure. 432 * @return A non-zero value if the calculation succeeded, zero 433 * otherwise. 434 */ 435 int cddb_disc_calc_discid(cddb_disc_t *disc); 436 437 /** 438 * Prints information about the disc on stdout. This is just a 439 * debugging routine to display the structure's content. 440 * 441 * @param disc The CDDB disc structure. 442 */ 443 void cddb_disc_print(cddb_disc_t *disc); 444 445 446 #ifdef __cplusplus 447 } 448 #endif 449 450 #endif /* CDDB_DISC_H */ 451