1 /* 2 Copyright (C) 2004, 2005, 2006, 2008, 2011, 2012 3 Rocky Bernstein <rocky@gnu.org> 4 Copyright (C) 2014 Robert Kausch <robert.kausch@freac.org> 5 Copyright (C) 2001 Xiph.org and Heiko Eissfeldt heiko@escape.colossus.de 6 7 This program is free software: you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation, either version 3 of the License, or 10 (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program. If not, see <http://www.gnu.org/licenses/>. 19 */ 20 21 /** \file cdda.h 22 * 23 * \brief The top-level interface header for libcdio_cdda. 24 * Applications include this for paranoia access. 25 * 26 ******************************************************************/ 27 28 #ifndef CDIO__PARANOIA__CDDA_H_ 29 #define CDIO__PARANOIA__CDDA_H_ 30 31 #include <cdio/cdio.h> 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif /* __cplusplus */ 36 37 /** cdrom_paranoia is an opaque structure which is used in all of the 38 library operations. 39 */ 40 typedef struct cdrom_paranoia_s cdrom_paranoia_t; 41 typedef struct cdrom_drive_s cdrom_drive_t; 42 43 /** For compatibility. cdrom_drive_t is deprecated, use cdrom_drive_t 44 instead. */ 45 46 /** 47 Flags for simulating jitter used in testing. 48 49 The enumeration type one probably wouldn't really use in a program. 50 It is here instead of defines to give symbolic names that can be 51 helpful in debuggers where wants just to say refer to 52 CDDA_TEST_JITTER_SMALL and get the correct value. 53 */ 54 typedef enum { 55 CDDA_MESSAGE_FORGETIT = 0, 56 CDDA_MESSAGE_PRINTIT = 1, 57 CDDA_MESSAGE_LOGIT = 2, 58 CD_FRAMESAMPLES = CDIO_CD_FRAMESIZE_RAW / 4, 59 MAXTRK = (CDIO_CD_MAX_TRACKS+1) 60 } paranoia_cdda_enums_t; 61 62 63 #include <signal.h> 64 65 /** We keep MAXTRK since this header is exposed publicly and other 66 programs may have used this. 67 */ 68 #define MAXTRK (CDIO_CD_MAX_TRACKS+1) 69 70 /** \brief Structure for cdparanoia's CD Table of Contents */ 71 typedef struct TOC_s { 72 unsigned char bTrack; 73 int32_t dwStartSector; 74 } TOC_t; 75 76 /** For compatibility. TOC is deprecated, use TOC_t instead. */ 77 #define TOC TOC_t 78 79 /** \brief Structure for cdparanoia's CD-ROM access */ 80 struct cdrom_drive_s { 81 82 CdIo_t *p_cdio; 83 int opened; /**< This struct may just represent a candidate for opening */ 84 85 char *cdda_device_name; 86 87 char *drive_model; 88 int drive_type; 89 int bigendianp; /**< Whether data returned on the CDDA is bigendian or 90 not. 1 if big endian, 0 if little endian and -1 if 91 we don't know. 92 */ 93 int nsectors; /**< Number of sectors use in reading. Multiply by 94 CDIO_CD_FRAMESIZE_RAW to get number of bytes used in 95 the read buffer. */ 96 97 int cd_extra; /**< -1 if we can't get multisession info, 0 if 98 there is one session only or the multi-session 99 LBA is less than or 100 (don't ask me why -- I 100 don't know), and 1 if the multi-session lba is 101 greater than 100. */ 102 103 bool b_swap_bytes; /**< Swap bytes if Endian-ness of drive 104 mismatches the endian-ness of the 105 computer? */ 106 track_t tracks; 107 TOC_t disc_toc[MAXTRK]; /**< info here starts origin 0 rather than the 108 first track number (usually 1). So to take 109 a track number and use it here, subtract 110 off cdio_get_first_track_num() beforehand. 111 */ 112 lsn_t audio_first_sector; 113 lsn_t audio_last_sector; 114 115 int errordest; 116 int messagedest; 117 char *errorbuf; 118 char *messagebuf; 119 120 /* functions specific to particular drives/interfaces */ 121 122 int (*enable_cdda) (cdrom_drive_t *d, int onoff); 123 int (*read_toc) (cdrom_drive_t *d); 124 long (*read_audio) (cdrom_drive_t *d, void *p, lsn_t begin, 125 long sectors); 126 int (*set_speed) (cdrom_drive_t *d, int speed); 127 int error_retry; 128 int report_all; 129 130 int is_atapi; 131 int is_mmc; 132 133 int last_milliseconds; 134 135 int i_test_flags; /**< Normally set 0. But if we are testing 136 paranoia operation this can be set to one of 137 the flag masks to simulate a particular kind of 138 failure. */ 139 140 }; 141 142 143 /** 144 Flags for simulating jitter used in testing. 145 146 The enumeration type one probably wouldn't really use in a program. 147 It is here instead of defines to give symbolic names that can be 148 helpful in debuggers where wants just to say refer to 149 CDDA_TEST_JITTER_SMALL and get the correct value. 150 */ 151 typedef enum { 152 CDDA_TEST_JITTER_SMALL = 1, 153 CDDA_TEST_JITTER_LARGE = 2, 154 CDDA_TEST_JITTER_MASSIVE = 3, 155 CDDA_TEST_FRAG_SMALL = (1<<3), 156 CDDA_TEST_FRAG_LARGE = (2<<3), 157 CDDA_TEST_FRAG_MASSIVE = (3<<3), 158 CDDA_TEST_UNDERRUN = 64 159 } paranoia_jitter_t; 160 161 /** jitter testing. The first two bits are set to determine the 162 byte-distance we will jitter the data; 0 is no shifting. 163 */ 164 165 /**< jitter testing. Set the below bit to always cause jittering on reads. 166 The below bit only has any effect if the first two (above) bits are 167 nonzero. If the above bits are set, but the below bit isn't we'll 168 jitter 90% of the time. 169 */ 170 #define CDDA_TEST_ALWAYS_JITTER 4 171 172 /** fragment testing */ 173 #define CDDA_TEST_FRAG_SMALL (1<<3) 174 #define CDDA_TEST_FRAG_LARGE (2<<3) 175 #define CDDA_TEST_FRAG_MASSIVE (3<<3) 176 177 /**< under-run testing. The below bit is set for testing. */ 178 #define CDDA_TEST_UNDERRUN 64 179 180 #if TESTING_IS_FINISHED 181 182 /** scratch testing */ 183 #define CDDA_TEST_SCRATCH 128 184 #undef CDDA_TEST_BOGUS_BYTES 256 185 #undef CDDA_TEST_DROPDUPE_BYTES 512 186 #endif /* TESTING_IS_FINISHED */ 187 188 /** autosense functions */ 189 190 /** Get a CD-ROM drive with a CD-DA in it. 191 If mesagedest is CDDA_MESSAGE_LOGIT, then any messages in the 192 process will be stored in message. 193 194 When using CDDA_MESSAGE_LOGIT, free the message buffer with 195 cdio_cddap_free_messages() after use. 196 */ 197 extern cdrom_drive_t *cdio_cddap_find_a_cdrom(int messagedest, 198 char **ppsz_message); 199 200 /** Returns a paranoia CD-ROM drive object with a CD-DA in it or NULL 201 if there was an error. 202 @see cdio_cddap_identify_cdio 203 204 When using CDDA_MESSAGE_LOGIT, free the message buffer with 205 cdio_cddap_free_messages() after use. 206 */ 207 extern cdrom_drive_t *cdio_cddap_identify(const char *psz_device, 208 int messagedest, 209 char **ppsz_message); 210 211 /** Returns a paranoia CD-ROM drive object with a CD-DA in it or NULL 212 if there was an error. In contrast to cdio_cddap_identify, we 213 start out with an initialized p_cdio object. For example you may 214 have used that for other purposes such as to get CDDB/CD-Text 215 information. @see cdio_cddap_identify 216 217 When using CDDA_MESSAGE_LOGIT, free the message buffer with 218 cdio_cddap_free_messages() after use. 219 */ 220 cdrom_drive_t *cdio_cddap_identify_cdio(CdIo_t *p_cdio, 221 int messagedest, char **ppsz_messages); 222 223 /** informational functions */ 224 225 extern const char *cdio_cddap_version(); 226 227 /** Returns the current message buffer. Free the returned 228 string using cdio_cddap_free_messages() if not NULL. 229 */ 230 extern char *cdio_cddap_messages(cdrom_drive_t *d); 231 232 /** Returns the current error buffer. Free the returned 233 string using cdio_cddap_free_messages() if not NULL. 234 */ 235 extern char *cdio_cddap_errors(cdrom_drive_t *d); 236 237 /** Frees the message string passed in psz_messages. 238 */ 239 extern void cdio_cddap_free_messages(char *psz_messages); 240 241 /** drive-oriented functions */ 242 243 extern int cdio_cddap_speed_set(cdrom_drive_t *d, int speed); 244 extern void cdio_cddap_verbose_set(cdrom_drive_t *d, int err_action, 245 int mes_action); 246 247 /*! 248 Closes d and releases all storage associated with it except 249 the internal p_cdio pointer. 250 251 @param d cdrom_drive_t object to be closed. 252 @return 0 if passed a null pointer and 1 if not in which case 253 some work was probably done. 254 255 @see cdio_cddap_close 256 */ 257 bool cdio_cddap_close_no_free_cdio(cdrom_drive_t *d); 258 259 /*! 260 Closes d and releases all storage associated with it. 261 Doubles as "cdrom_drive_free()". 262 263 @param d cdrom_drive_t object to be closed. 264 @return 0 if passed a null pointer and 1 if not in which case 265 some work was probably done. 266 267 @see cdio_cddap_close_no_free_cdio 268 */ 269 extern int cdio_cddap_close(cdrom_drive_t *d); 270 271 extern int cdio_cddap_open(cdrom_drive_t *d); 272 273 extern long cdio_cddap_read(cdrom_drive_t *d, void *p_buffer, 274 lsn_t beginsector, long sectors); 275 276 extern long cdio_cddap_read_timed(cdrom_drive_t *d, void *p_buffer, 277 lsn_t beginsector, long sectors, int *milliseconds); 278 279 /*! Return the lsn for the start of track i_track */ 280 extern lsn_t cdio_cddap_track_firstsector(cdrom_drive_t *d, 281 track_t i_track); 282 283 /*! Get last lsn of the track. This generally one less than the start 284 of the next track. -1 is returned on error. */ 285 extern lsn_t cdio_cddap_track_lastsector(cdrom_drive_t *d, track_t i_track); 286 287 /*! Return the number of tracks on the CD. */ 288 extern track_t cdio_cddap_tracks(cdrom_drive_t *d); 289 290 /*! Return the track containing the given LSN. If the LSN is before 291 the first track (in the pregap), 0 is returned. If there was an 292 error or the LSN after the LEADOUT (beyond the end of the CD), then 293 CDIO_INVALID_TRACK is returned. 294 */ 295 extern int cdio_cddap_sector_gettrack(cdrom_drive_t *d, lsn_t lsn); 296 297 /*! Return the number of channels in track: 2 or 4; -2 if not 298 implemented or -1 for error. 299 Not meaningful if track is not an audio track. 300 */ 301 extern int cdio_cddap_track_channels(cdrom_drive_t *d, track_t i_track); 302 303 /*! Return 1 is track is an audio track, 0 otherwise. */ 304 extern int cdio_cddap_track_audiop(cdrom_drive_t *d, track_t i_track); 305 306 /*! Return 1 is track has copy permit set, 0 otherwise. */ 307 extern int cdio_cddap_track_copyp(cdrom_drive_t *d, track_t i_track); 308 309 /*! Return 1 is audio track has linear preemphasis set, 0 otherwise. 310 Only makes sense for audio tracks. 311 */ 312 extern int cdio_cddap_track_preemp(cdrom_drive_t *d, track_t i_track); 313 314 /*! Get first lsn of the first audio track. -1 is returned on error. */ 315 extern lsn_t cdio_cddap_disc_firstsector(cdrom_drive_t *d); 316 317 /*! Get last lsn of the last audio track. The last lsn is generally one 318 less than the start of the next track after the audio track. -1 is 319 returned on error. */ 320 extern lsn_t cdio_cddap_disc_lastsector(cdrom_drive_t *d); 321 322 /*! Determine Endian-ness of the CD-drive based on reading data from 323 it. Some drives return audio data Big Endian while some (most) 324 return data Little Endian. Drives known to return data bigendian are 325 SCSI drives from Kodak, Ricoh, HP, Philips, Plasmon, Grundig 326 CDR100IPW, and Mitsumi CD-R. ATAPI and MMC drives are little endian. 327 328 rocky: As someone who didn't write the code, I have to say this is 329 nothing less than brilliant. An FFT is done both ways and the the 330 transform is looked at to see which has data in the FFT (or audible) 331 portion. (Or so that's how I understand it.) 332 333 @return 1 if big-endian, 0 if little-endian, -1 if we couldn't 334 figure things out or some error. 335 */ 336 extern int data_bigendianp(cdrom_drive_t *d); 337 338 /** transport errors: */ 339 340 typedef enum { 341 TR_OK = 0, 342 TR_EWRITE = 1 /**< Error writing packet command (transport) */, 343 TR_EREAD = 2 /**< Error reading packet data (transport) */, 344 TR_UNDERRUN = 3 /**< Read underrun */, 345 TR_OVERRUN = 4 /**< Read overrun */, 346 TR_ILLEGAL = 5 /**< Illegal/rejected request */, 347 TR_MEDIUM = 6 /**< Medium error */, 348 TR_BUSY = 7 /**< Device busy */, 349 TR_NOTREADY = 8 /**< Device not ready */, 350 TR_FAULT = 9 /**< Device failure */, 351 TR_UNKNOWN = 10 /**< Unspecified error */, 352 TR_STREAMING = 11 /**< loss of streaming */, 353 } transport_error_t; 354 355 356 #ifdef NEED_STRERROR_TR 357 const char *strerror_tr[]={ 358 "Success", 359 "Error writing packet command to device", 360 "Error reading command from device", 361 "SCSI packet data underrun (too little data)", 362 "SCSI packet data overrun (too much data)", 363 "Illegal SCSI request (rejected by target)", 364 "Medium reading data from medium", 365 "Device busy", 366 "Device not ready", 367 "Target hardware fault", 368 "Unspecified error", 369 "Drive lost streaming" 370 }; 371 #endif /*NEED_STERROR_TR*/ 372 373 /** Errors returned by lib: 374 375 \verbatim 376 001: Unable to set CDROM to read audio mode 377 002: Unable to read table of contents lead-out 378 003: CDROM reporting illegal number of tracks 379 004: Unable to read table of contents header 380 005: Unable to read table of contents entry 381 006: Could not read any data from drive 382 007: Unknown, unrecoverable error reading data 383 008: Unable to identify CDROM model 384 009: CDROM reporting illegal table of contents 385 010: Unaddressable sector 386 387 100: Interface not supported 388 101: Drive is neither a CDROM nor a WORM device 389 102: Permision denied on cdrom (ioctl) device 390 103: Permision denied on cdrom (data) device 391 392 300: Kernel memory error 393 394 400: Device not open 395 401: Invalid track number 396 402: Track not audio data 397 403: No audio tracks on disc 398 404: No medium present 399 405: Option not supported by drive 400 \endverbatim 401 402 */ 403 404 #ifndef DO_NOT_WANT_PARANOIA_COMPATIBILITY 405 /** For compatibility with good ol' paranoia */ 406 #define cdda_find_a_cdrom cdio_cddap_find_a_cdrom 407 #define cdda_identify cdio_cddap_identify 408 #define cdda_version cdio_cddap_version 409 #define cdda_speed_set cdio_cddap_speed_set 410 #define cdda_verbose_set cdio_cddap_verbose_set 411 #define cdda_messages cdio_cddap_messages 412 #define cdda_errors cdio_cddap_errors 413 #define cdda_close cdio_cddap_close 414 #define cdda_open cdio_cddap_open 415 #define cdda_read cdio_cddap_read 416 #define cdda_read_timed cdio_cddap_read_timed 417 #define cdda_track_firstsector cdio_cddap_track_firstsector 418 #define cdda_track_lastsector cdio_cddap_track_lastsector 419 #define cdda_tracks cdio_cddap_tracks 420 #define cdda_sector_gettrack cdio_cddap_sector_gettrack 421 #define cdda_track_channels cdio_cddap_track_channels 422 #define cdda_track_audiop cdio_cddap_track_audiop 423 #define cdda_track_copyp cdio_cddap_track_copyp 424 #define cdda_track_preemp cdio_cddap_track_preemp 425 #define cdda_disc_firstsector cdio_cddap_disc_firstsector 426 #define cdda_disc_lastsector cdio_cddap_disc_lastsector 427 #define cdrom_drive cdrom_drive_t 428 429 #endif /*DO_NOT_WANT_PARANOIA_COMPATIBILITY*/ 430 431 #ifdef __cplusplus 432 } 433 #endif /* __cplusplus */ 434 435 /** The below variables are trickery to force the above enum symbol 436 values to be recorded in debug symbol tables. They are used to 437 allow one to refer to the enumeration value names in the typedefs 438 above in a debugger and debugger expressions 439 */ 440 441 extern paranoia_jitter_t debug_paranoia_jitter; 442 extern paranoia_cdda_enums_t debug_paranoia_cdda_enums; 443 444 #ifdef __cplusplus 445 extern "C" { 446 #endif 447 extern const char *cdio_cddap_version(void); 448 extern void cdio_cddap_free_messages(char *psz_messages); 449 450 #ifdef __cplusplus 451 } 452 #endif 453 454 #endif /*CDIO__PARANOIA__CDDA_H_*/ 455