1 /* 2 Copyright (C) 2004, 2005, 2006, 2007, 2008, 2011, 2012 3 2017 Rocky Bernstein <rocky@gnu.org> 4 Copyright (C) 2014 Robert Kausch <robert.kausch@freac.org> 5 Copyright (C) 1998 Monty xiphmont@mit.edu 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 paranoia.h 22 * 23 * \brief The top-level header for libcdda_paranoia: a device- and OS- 24 * independent library for reading CD-DA with error tolerance and 25 * repair. Applications include this for paranoia access. 26 */ 27 28 #ifndef CDIO__PARANOIA__PARANOIA_H_ 29 #define CDIO__PARANOIA__PARANOIA_H_ 30 31 #include <cdio/paranoia/cdda.h> 32 33 /*! Paranoia likes to work with 16-bit numbers rather than 34 (possibly byte-swapped) bytes. So there are this many 35 16-bit numbers block (frame, or sector) read. 36 */ 37 #define CD_FRAMEWORDS (CDIO_CD_FRAMESIZE_RAW/2) 38 39 /** 40 Flags used in paranoia_modeset. 41 42 The enumeration type one probably wouldn't really use in a program. 43 It is here instead of defines to give symbolic names that can be 44 helpful in debuggers where wants just to say refer to 45 PARANOIA_MODE_DISABLE and get the correct value. 46 */ 47 48 typedef enum { 49 PARANOIA_MODE_DISABLE = 0x00, /**< No fixups */ 50 PARANOIA_MODE_VERIFY = 0x01, /**< Verify data integrety in overlap area*/ 51 PARANOIA_MODE_FRAGMENT = 0x02, /**< unsupported */ 52 PARANOIA_MODE_OVERLAP = 0x04, /**< Perform overlapped reads */ 53 PARANOIA_MODE_SCRATCH = 0x08, /**< unsupported */ 54 PARANOIA_MODE_REPAIR = 0x10, /**< unsupported */ 55 PARANOIA_MODE_NEVERSKIP = 0x20, /**< Do not skip failed reads (retry 56 maxretries) */ 57 PARANOIA_MODE_FULL = 0xff, /**< Maximum paranoia - all of the above 58 (except disable) */ 59 } paranoia_mode_t; 60 61 62 /** 63 Flags set in a callback. 64 65 The enumeration type one probably wouldn't really use in a program. 66 It is here instead of defines to give symbolic names that can be 67 helpful in debuggers where wants just to say refer to 68 PARANOIA_CB_READ and get the correct value. 69 */ 70 typedef enum { 71 PARANOIA_CB_READ, /**< Read off adjust ??? */ 72 PARANOIA_CB_VERIFY, /**< Verifying jitter */ 73 PARANOIA_CB_FIXUP_EDGE, /**< Fixed edge jitter */ 74 PARANOIA_CB_FIXUP_ATOM, /**< Fixed atom jitter */ 75 PARANOIA_CB_SCRATCH, /**< Unsupported */ 76 PARANOIA_CB_REPAIR, /**< Unsupported */ 77 PARANOIA_CB_SKIP, /**< Skip exhausted retry */ 78 PARANOIA_CB_DRIFT, /**< Skip exhausted retry */ 79 PARANOIA_CB_BACKOFF, /**< Unsupported */ 80 PARANOIA_CB_OVERLAP, /**< Dynamic overlap adjust */ 81 PARANOIA_CB_FIXUP_DROPPED, /**< Fixed dropped bytes */ 82 PARANOIA_CB_FIXUP_DUPED, /**< Fixed duplicate bytes */ 83 PARANOIA_CB_READERR, /**< Hard read error */ 84 PARANOIA_CB_CACHEERR, /**< Bad cache management */ 85 PARANOIA_CB_WROTE, /**< Wrote block "*" */ 86 PARANOIA_CB_FINISHED /**< Finished writing "*" */ 87 } paranoia_cb_mode_t; 88 89 extern const char *paranoia_cb_mode2str[]; 90 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 /*! 96 Get libcdio-paranoia version. 97 98 @return paranoia version string 99 */ 100 extern const char *cdio_paranoia_version(void); 101 102 /*! 103 Get and initialize a new cdrom_paranoia object from cdrom_drive. 104 Run this before calling any of the other paranoia routines below. 105 106 @return new cdrom_paranoia object Call paranoia_free() when you are 107 done with it 108 */ 109 extern cdrom_paranoia_t *cdio_paranoia_init(cdrom_drive_t *d); 110 111 /*! 112 Free any resources associated with p. 113 114 @param p paranoia object to for which resources are to be freed. 115 116 @see paranoia_init. 117 */ 118 extern void cdio_paranoia_free(cdrom_paranoia_t *p); 119 120 /*! 121 Set the kind of repair you want to on for reading. 122 The modes are listed above 123 124 @param p paranoia type 125 @param mode_flags paranoia mode flags built from values in 126 paranoia_mode_t, e.g. 127 PARANOIA_MODE_FULL^PARANOIA_MODE_NEVERSKIP 128 */ 129 extern void cdio_paranoia_modeset(cdrom_paranoia_t *p, int mode_flags); 130 131 /*! 132 reposition reading offset. 133 134 @param p paranoia type 135 @param seek byte offset to seek to 136 @param whence like corresponding parameter in libc's lseek, e.g. 137 SEEK_SET or SEEK_END. 138 */ 139 extern lsn_t cdio_paranoia_seek(cdrom_paranoia_t *p, int32_t seek, 140 int whence); 141 142 /*! 143 Reads the next sector of audio data and returns a pointer to a full 144 sector of verified samples. 145 146 @param p paranoia object. 147 148 @param callback callback routine which gets called with the status 149 on each read. 150 151 @return the audio data read, CDIO_CD_FRAMESIZE_RAW (2352) 152 bytes. This data is not to be freed by the caller. It will persist 153 only until the next call to paranoia_read() for this p. 154 */ 155 extern int16_t *cdio_paranoia_read(cdrom_paranoia_t *p, 156 void(*callback)(long int, 157 paranoia_cb_mode_t)); 158 159 /*! The same as cdio_paranoia_read but the number of retries is set. 160 @param p paranoia object. 161 162 @param callback callback routine which gets called with the status 163 on each read. 164 165 @param max_retries number of times to try re-reading a block before 166 failing. 167 168 @return the block of CDIO_FRAMEIZE_RAW bytes (or 169 CDIO_FRAMESIZE_RAW / 2 16-bit integers). Unless byte-swapping has 170 been turned off the 16-bit integers Endian independent order. 171 172 @see cdio_paranoia_read. 173 174 */ 175 extern int16_t *cdio_paranoia_read_limited(cdrom_paranoia_t *p, 176 void(*callback)(long int, 177 paranoia_cb_mode_t), 178 int max_retries); 179 180 181 /*! a temporary hack */ 182 extern void cdio_paranoia_overlapset(cdrom_paranoia_t *p,long overlap); 183 184 extern void cdio_paranoia_set_range(cdrom_paranoia_t *p, long int start, 185 long int end); 186 187 /*! 188 Set or query the number of sectors used for paranoia cache modelling. 189 190 @param p paranoia object 191 @param sectors number of sectors to use, default is 1200 (pass -1 to 192 query current model size without setting a new value) 193 194 @return number of cache sectors before the call 195 */ 196 extern int cdio_paranoia_cachemodel_size(cdrom_paranoia_t *p,int sectors); 197 198 #ifndef DO_NOT_WANT_PARANOIA_COMPATIBILITY 199 /** For compatibility with good ol' paranoia */ 200 #define cdrom_paranoia cdrom_paranoia_t 201 #define paranoia_version cdio_paranoia_version 202 #define paranoia_init cdio_paranoia_init 203 #define paranoia_free cdio_paranoia_free 204 #define paranoia_modeset cdio_paranoia_modeset 205 #define paranoia_seek cdio_paranoia_seek 206 #define paranoia_read cdio_paranoia_read 207 #define paranoia_read_limited cdio_paranoia_read_limited 208 #define paranoia_overlapset cdio_paranoia_overlapset 209 #define paranoia_set_range cdio_paranoia_set_range 210 #define paranoia_cachemodel_size cdio_paranoia_cachemodel_size 211 #endif /*DO_NOT_WANT_PARANOIA_COMPATIBILITY*/ 212 213 #ifdef __cplusplus 214 } 215 #endif 216 217 /** The below variables are trickery to force the above enum symbol 218 values to be recorded in debug symbol tables. They are used to 219 allow one to refer to the enumeration value names in the typedefs 220 above in a debugger and debugger expressions 221 */ 222 223 extern paranoia_mode_t debug_paranoia_mode; 224 extern paranoia_cb_mode_t debug_paranoia_cb_mode; 225 226 #endif /*CDIO__PARANOIA__PARANOIA_H_*/ 227