1 /* -*- c -*- 2 3 Copyright (C) 2005-2006, 2008-2013 Rocky Bernstein <rocky@gnu.org> 4 5 This program is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation, either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 /** 20 * \file device.h 21 * 22 * \brief C header for driver- or device-related libcdio 23 * calls. ("device" includes CD-image reading devices). 24 */ 25 #ifndef CDIO_DEVICE_H_ 26 #define CDIO_DEVICE_H_ 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 #include <cdio/types.h> 33 #include <cdio/cdio.h> 34 35 /** The type of an drive capability bit mask. See below for values*/ 36 typedef uint32_t cdio_drive_read_cap_t; 37 typedef uint32_t cdio_drive_write_cap_t; 38 typedef uint32_t cdio_drive_misc_cap_t; 39 40 /** 41 \brief Drive capability bits returned by cdio_get_drive_cap() 42 NOTE: Setting a bit here means the presence of a capability. 43 */ 44 45 /** Miscellaneous capabilities. */ 46 typedef enum { 47 CDIO_DRIVE_CAP_ERROR = 0x40000, /**< Error */ 48 CDIO_DRIVE_CAP_UNKNOWN = 0x80000, /**< Dunno. It can be on if we 49 have only partial information 50 or are not completely certain 51 */ 52 CDIO_DRIVE_CAP_MISC_CLOSE_TRAY = 0x00001, /**< caddy systems can't 53 close... */ 54 CDIO_DRIVE_CAP_MISC_EJECT = 0x00002, /**< but can eject. */ 55 CDIO_DRIVE_CAP_MISC_LOCK = 0x00004, /**< disable manual eject */ 56 CDIO_DRIVE_CAP_MISC_SELECT_SPEED = 0x00008, /**< programmable speed */ 57 CDIO_DRIVE_CAP_MISC_SELECT_DISC = 0x00010, /**< select disc from 58 juke-box */ 59 CDIO_DRIVE_CAP_MISC_MULTI_SESSION= 0x00020, /**< read sessions>1 */ 60 CDIO_DRIVE_CAP_MISC_MEDIA_CHANGED= 0x00080, /**< media changed */ 61 CDIO_DRIVE_CAP_MISC_RESET = 0x00100, /**< hard reset device */ 62 CDIO_DRIVE_CAP_MISC_FILE = 0x20000 /**< drive is really a file, 63 i.e a CD file image */ 64 } cdio_drive_cap_misc_t; 65 66 /** Reading masks.. */ 67 typedef enum { 68 CDIO_DRIVE_CAP_READ_AUDIO = 0x00001, /**< drive can play CD audio */ 69 CDIO_DRIVE_CAP_READ_CD_DA = 0x00002, /**< drive can read CD-DA */ 70 CDIO_DRIVE_CAP_READ_CD_G = 0x00004, /**< drive can read CD+G */ 71 CDIO_DRIVE_CAP_READ_CD_R = 0x00008, /**< drive can read CD-R */ 72 CDIO_DRIVE_CAP_READ_CD_RW = 0x00010, /**< drive can read CD-RW */ 73 CDIO_DRIVE_CAP_READ_DVD_R = 0x00020, /**< drive can read DVD-R */ 74 CDIO_DRIVE_CAP_READ_DVD_PR = 0x00040, /**< drive can read DVD+R */ 75 CDIO_DRIVE_CAP_READ_DVD_RAM = 0x00080, /**< drive can read DVD-RAM */ 76 CDIO_DRIVE_CAP_READ_DVD_ROM = 0x00100, /**< drive can read DVD-ROM */ 77 CDIO_DRIVE_CAP_READ_DVD_RW = 0x00200, /**< drive can read DVD-RW */ 78 CDIO_DRIVE_CAP_READ_DVD_RPW = 0x00400, /**< drive can read DVD+RW */ 79 CDIO_DRIVE_CAP_READ_C2_ERRS = 0x00800, /**< has C2 error correction */ 80 CDIO_DRIVE_CAP_READ_MODE2_FORM1 = 0x01000, /**< can read mode 2 form 1 */ 81 CDIO_DRIVE_CAP_READ_MODE2_FORM2 = 0x02000, /**< can read mode 2 form 2 */ 82 CDIO_DRIVE_CAP_READ_MCN = 0x04000, /**< can read MCN */ 83 CDIO_DRIVE_CAP_READ_ISRC = 0x08000 /**< can read ISRC */ 84 } cdio_drive_cap_read_t; 85 86 /** Writing masks.. */ 87 typedef enum { 88 CDIO_DRIVE_CAP_WRITE_CD_R = 0x00001, /**< drive can write CD-R */ 89 CDIO_DRIVE_CAP_WRITE_CD_RW = 0x00002, /**< drive can write CD-RW */ 90 CDIO_DRIVE_CAP_WRITE_DVD_R = 0x00004, /**< drive can write DVD-R */ 91 CDIO_DRIVE_CAP_WRITE_DVD_PR = 0x00008, /**< drive can write DVD+R */ 92 CDIO_DRIVE_CAP_WRITE_DVD_RAM = 0x00010, /**< drive can write DVD-RAM */ 93 CDIO_DRIVE_CAP_WRITE_DVD_RW = 0x00020, /**< drive can write DVD-RW */ 94 CDIO_DRIVE_CAP_WRITE_DVD_RPW = 0x00040, /**< drive can write DVD+RW */ 95 CDIO_DRIVE_CAP_WRITE_MT_RAINIER = 0x00080, /**< Mount Rainier */ 96 CDIO_DRIVE_CAP_WRITE_BURN_PROOF = 0x00100, /**< burn proof */ 97 CDIO_DRIVE_CAP_WRITE_CD = 98 (CDIO_DRIVE_CAP_WRITE_CD_R | CDIO_DRIVE_CAP_WRITE_CD_RW), 99 /**< Has some sort of CD writer ability */ 100 101 CDIO_DRIVE_CAP_WRITE_DVD = 102 (CDIO_DRIVE_CAP_WRITE_DVD_R | CDIO_DRIVE_CAP_WRITE_DVD_PR 103 | CDIO_DRIVE_CAP_WRITE_DVD_RAM | CDIO_DRIVE_CAP_WRITE_DVD_RW 104 | CDIO_DRIVE_CAP_WRITE_DVD_RPW ), 105 /**< Has some sort of DVD writer ability */ 106 107 CDIO_DRIVE_CAP_WRITE = 108 (CDIO_DRIVE_CAP_WRITE_CD | CDIO_DRIVE_CAP_WRITE_DVD) 109 /**< Has some sort of DVD or CD writing ability */ 110 } cdio_drive_cap_write_t; 111 112 /** Size of fields returned by an \p INQUIRY command */ 113 typedef enum { 114 CDIO_MMC_HW_VENDOR_LEN = 8, /**< length of vendor field */ 115 CDIO_MMC_HW_MODEL_LEN = 16, /**< length of model field */ 116 CDIO_MMC_HW_REVISION_LEN = 4 /**< length of revision field */ 117 } cdio_mmc_hw_len_t; 118 119 120 /** \brief Structure to return CD vendor, model, and revision-level 121 strings obtained via the \p INQUIRY command */ 122 typedef struct cdio_hwinfo 123 { 124 char psz_vendor [CDIO_MMC_HW_VENDOR_LEN+1]; 125 char psz_model [CDIO_MMC_HW_MODEL_LEN+1]; 126 char psz_revision[CDIO_MMC_HW_REVISION_LEN+1]; 127 } cdio_hwinfo_t; 128 129 130 /** Flags specifying the category of device to open or is opened. */ 131 typedef enum { 132 CDIO_SRC_IS_DISK_IMAGE_MASK = 0x0001, /**< Read source is a CD image. */ 133 CDIO_SRC_IS_DEVICE_MASK = 0x0002, /**< Read source is a CD device. */ 134 CDIO_SRC_IS_SCSI_MASK = 0x0004, /**< Read source SCSI device. */ 135 CDIO_SRC_IS_NATIVE_MASK = 0x0008 136 } cdio_src_category_mask_t; 137 138 139 /** 140 * The driver_id_t enumerations may be used to tag a specific driver 141 * that is opened or is desired to be opened. Note that this is 142 * different than what is available on a given host. 143 * 144 * Order should not be changed lightly because it breaks the ABI. 145 * One is not supposed to iterate over the values, but iterate over the 146 * cdio_drivers and cdio_device_drivers arrays. 147 * 148 * NOTE: IF YOU MODIFY ENUM MAKE SURE INITIALIZATION IN CDIO.C AGREES. 149 * 150 */ 151 typedef enum { 152 DRIVER_UNKNOWN, /**< Used as input when we don't care what kind 153 of driver to use. */ 154 DRIVER_AIX, /**< AIX driver */ 155 DRIVER_FREEBSD, /**< FreeBSD driver - includes CAM and ioctl access */ 156 DRIVER_NETBSD, /**< NetBSD Driver. */ 157 DRIVER_LINUX, /**< GNU/Linux Driver */ 158 DRIVER_SOLARIS, /**< Sun Solaris Driver */ 159 DRIVER_OSX, /**< Apple OSX (or MacOS) Driver */ 160 DRIVER_WIN32, /**< Microsoft Windows Driver. Includes ASPI and 161 ioctl access. */ 162 DRIVER_CDRDAO, /**< cdrdao format CD image. This is listed 163 before BIN/CUE, to make the code prefer cdrdao 164 over BIN/CUE when both exist. */ 165 DRIVER_BINCUE, /**< CDRWIN BIN/CUE format CD image. This is 166 listed before NRG, to make the code prefer 167 BIN/CUE over NRG when both exist. */ 168 DRIVER_NRG, /**< Nero NRG format CD image. */ 169 DRIVER_DEVICE /**< Is really a set of the above; should come last */ 170 } driver_id_t; 171 172 /** 173 A null-terminated (that is DRIVER_UNKNOWN-terminated) ordered (in 174 order of preference) array of drivers. 175 */ 176 extern const driver_id_t cdio_drivers[]; 177 178 /** 179 A null-terminated (that is DRIVER_UNKNOWN-terminated) ordered (in 180 order of preference) array of device drivers. 181 */ 182 extern const driver_id_t cdio_device_drivers[]; 183 184 /** 185 There will generally be only one hardware for a given 186 build/platform from the list above. You can use the variable 187 below to determine which you've got. If the build doesn't make an 188 hardware driver, then the value will be DRIVER_UNKNOWN. 189 */ 190 extern const driver_id_t cdio_os_driver; 191 192 193 /** 194 The following are status codes for completion of a given cdio 195 operation. By design 0 is successful completion and -1 is error 196 completion. This is compatable with ioctl so those routines that 197 call ioctl can just pass the value the get back (cast as this 198 enum). Also, by using negative numbers for errors, the 199 enumeration values below can be used in places where a positive 200 value is expected when things complete successfully. For example, 201 get_blocksize returns the blocksize, but on error uses the error 202 codes below. So note that this enumeration is often cast to an 203 integer. C seems to tolerate this. 204 */ 205 typedef enum { 206 DRIVER_OP_SUCCESS = 0, /**< in cases where an int is 207 returned, like cdio_set_speed, 208 more the negative return codes are 209 for errors and the positive ones 210 for success. */ 211 DRIVER_OP_ERROR = -1, /**< operation returned an error */ 212 DRIVER_OP_UNSUPPORTED = -2, /**< returned when a particular driver 213 doesn't support a particular operation. 214 For example an image driver which doesn't 215 really "eject" a CD. 216 */ 217 DRIVER_OP_UNINIT = -3, /**< returned when a particular driver 218 hasn't been initialized or a null 219 pointer has been passed. 220 */ 221 DRIVER_OP_NOT_PERMITTED = -4, /**< Operation not permitted. 222 For example might be a permission 223 problem. 224 */ 225 DRIVER_OP_BAD_PARAMETER = -5, /**< Bad parameter passed */ 226 DRIVER_OP_BAD_POINTER = -6, /**< Bad pointer to memory area */ 227 DRIVER_OP_NO_DRIVER = -7, /**< Operation called on a driver 228 not available on this OS */ 229 DRIVER_OP_MMC_SENSE_DATA = -8, /**< MMC operation returned sense data, 230 but no other error above recorded. */ 231 } driver_return_code_t; 232 233 /** 234 Close media tray in CD drive if there is a routine to do so. 235 236 @param psz_drive the name of CD-ROM to be closed. If NULL, we will 237 use the default device. 238 239 @param p_driver_id is the driver to be used or that got used if 240 it was \p DRIVER_UNKNOWN or \p DRIVER_DEVICE; If this is \p NULL, we won't 241 report back the driver used. 242 */ 243 driver_return_code_t cdio_close_tray (const char *psz_drive, 244 /*in/out*/ driver_id_t *p_driver_id); 245 246 /** 247 @param drc the return code you want interpreted. 248 249 @return the string information about \p drc 250 */ 251 const char *cdio_driver_errmsg(driver_return_code_t drc); 252 253 /** 254 Eject media in CD drive if there is a routine to do so. 255 256 @param p_cdio the CD object to be acted upon. 257 If the CD is ejected \p *p_cdio is free'd and p_cdio set to \p NULL. 258 */ 259 driver_return_code_t cdio_eject_media (CdIo_t **p_cdio); 260 261 /** 262 Eject media in CD drive if there is a routine to do so. 263 264 @param psz_drive the name of the device to be acted upon. 265 If NULL is given as the drive, we'll use the default driver device. 266 */ 267 driver_return_code_t cdio_eject_media_drive (const char *psz_drive); 268 269 /** 270 Free device list returned by cdio_get_devices or 271 cdio_get_devices_with_cap(). 272 273 @param device_list list returned by cdio_get_devices or 274 cdio_get_devices_with_cap(). 275 276 @see cdio_get_devices(), and cdio_get_devices_with_cap(). 277 278 */ 279 void cdio_free_device_list (char * device_list[]); 280 281 /** 282 Get the default CD device. 283 if \p p_cdio is \p NULL (we haven't initialized a specific device driver), 284 then find a suitable one and return the default device for that. 285 286 @param p_cdio the CD object queried 287 288 @return a string containing the default CD device or \p NULL 289 if we couldn't get a default device. 290 291 In some situations of drivers or OS's we can't find a CD device if 292 there is no media in it and it is possible for this routine to return 293 NULL even though there may be a hardware CD-ROM. 294 */ 295 char * cdio_get_default_device (const CdIo_t *p_cdio); 296 297 /** 298 Return a string containing the default CD device if none is specified. 299 if \p p_driver_id is \p DRIVER_UNKNOWN or \p DRIVER_DEVICE 300 then find a suitable one set the default device for that. 301 302 \p NULL is returned if we couldn't get a default device. 303 */ 304 char * cdio_get_default_device_driver (/*in/out*/ driver_id_t *p_driver_id); 305 306 /** Return an array of device names. If you want a specific 307 devices for a driver, give that device. If you want hardware 308 devices, give \p DRIVER_DEVICE and if you want all possible devices, 309 image drivers and hardware drivers give \p DRIVER_UNKNOWN. 310 311 NULL is returned if we couldn't return a list of devices. 312 313 In some situations of drivers or OS's we can't find a CD device if 314 there is no media in it and it is possible for this routine to return 315 \p NULL even though there may be a hardware CD-ROM. 316 */ 317 char ** cdio_get_devices (driver_id_t driver_id); 318 319 /** 320 Get an array of device names in search_devices that have at least 321 the capabilities listed by the capabities parameter. If 322 search_devices is \p NULL, then we'll search all possible CD drives. 323 324 Capabilities have two parts to them, a "filesystem" part and an 325 "analysis" part. 326 327 The filesystem part is mutually exclusive. For example either the 328 filesystem is at most one of the High-Sierra, UFS, or HFS, 329 ISO9660, fileystems. Valid combinations of say HFS and ISO9660 330 are specified as a separate "filesystem". 331 332 Capabilities on the other hand are not mutually exclusive. For 333 example a filesystem may have none, either, or both of the XA or 334 Rock-Ridge extension properties. 335 336 If "b_any" is set false then every capability listed in the 337 analysis portion of capabilities (i.e. not the basic filesystem) 338 must be satisified. If no analysis capabilities are specified, 339 that's a match. 340 341 If "b_any" is set true, then if any of the analysis capabilities 342 matches, we call that a success. 343 344 In either case, in the filesystem portion different filesystem 345 either specify 0 to match any filesystem or the specific 346 filesystem type. 347 348 To find a CD-drive of any type, use the mask CDIO_FS_MATCH_ALL. 349 350 @return the array of device names or NULL if we couldn't get a 351 default device. It is also possible to return a non NULL but 352 after dereferencing the the value is NULL. This also means nothing 353 was found. 354 */ 355 char ** cdio_get_devices_with_cap (/*in*/ char *ppsz_search_devices[], 356 cdio_fs_anal_t capabilities, bool b_any); 357 358 /** 359 Like cdio_get_devices_with_cap() but we return the driver we found 360 as well. This is because often one wants to search for kind of drive 361 and then *open* it afterwards. Giving the driver back facilitates this, 362 and speeds things up for libcdio as well. 363 */ 364 char ** cdio_get_devices_with_cap_ret (/*in*/ char* ppsz_search_devices[], 365 cdio_fs_anal_t capabilities, 366 bool b_any, 367 /*out*/ driver_id_t *p_driver_id); 368 369 /** 370 Like cdio_get_devices(), but we may change the p_driver_id if we 371 were given \p DRIVER_DEVICE or \p DRIVER_UNKNOWN. This is because often 372 one wants to get a drive name and then *open* it 373 afterwards. Giving the driver back facilitates this, and speeds 374 things up for libcdio as well. 375 */ 376 377 char ** cdio_get_devices_ret (/*in/out*/ driver_id_t *p_driver_id); 378 379 /** 380 Get the what kind of device we've got. 381 382 @param p_cdio the CD object queried 383 @param p_read_cap pointer to return read capabilities 384 @param p_write_cap pointer to return write capabilities 385 @param p_misc_cap pointer to return miscellaneous other capabilities 386 387 In some situations of drivers or OS's we can't find a CD device if 388 there is no media in it. In this situation capabilities will show up as 389 \p NULL even though there isa hardware CD-ROM. 390 */ 391 void cdio_get_drive_cap (const CdIo_t *p_cdio, 392 cdio_drive_read_cap_t *p_read_cap, 393 cdio_drive_write_cap_t *p_write_cap, 394 cdio_drive_misc_cap_t *p_misc_cap); 395 396 /** 397 Get the drive capabilities for a specified device. 398 399 Return a list of device capabilities. 400 401 In some situations of drivers or OS's we can't find a CD device if 402 there is no media in it. In this situation capabilities will show up as 403 \p NULL even though there isa hardware CD-ROM. 404 */ 405 void cdio_get_drive_cap_dev (const char *device, 406 cdio_drive_read_cap_t *p_read_cap, 407 cdio_drive_write_cap_t *p_write_cap, 408 cdio_drive_misc_cap_t *p_misc_cap); 409 410 /** 411 Get a string containing the name of the driver in use. 412 413 @param p_cdio the CD object to be acted upon. 414 415 @return a string with driver name or NULL if CdIo_t is NULL (we 416 haven't initialized a specific device. 417 */ 418 const char * cdio_get_driver_name (const CdIo_t *p_cdio); 419 420 /** 421 Return a string name for the \p driver_id. 422 */ 423 const char * cdio_get_driver_name_from_id (driver_id_t driver_id); 424 425 426 /** 427 Get the driver id. 428 if \p p_cdio is \p NULL (we haven't initialized a specific device driver), 429 then return \p DRIVER_UNKNOWN. 430 431 @param p_cdio the CD object to be acted upon. 432 433 @return the driver id.. 434 */ 435 driver_id_t cdio_get_driver_id (const CdIo_t *p_cdio); 436 437 /** 438 Get the CD-ROM hardware info via a SCSI MMC INQUIRY command. 439 False is returned if we had an error getting the information. 440 */ 441 bool cdio_get_hwinfo ( const CdIo_t *p_cdio, 442 /*out*/ cdio_hwinfo_t *p_hw_info ); 443 444 445 /** 446 Get the LSN of the first track of the last session of 447 on the CD. 448 449 @param p_cdio the CD object to be acted upon. 450 @param i_last_session pointer to the session number to be returned. 451 */ 452 driver_return_code_t cdio_get_last_session (CdIo_t *p_cdio, 453 /*out*/ lsn_t *i_last_session); 454 455 /** 456 Find out if media has changed since the last call. 457 458 @param p_cdio the CD object to be acted upon. 459 460 @return 1 if media has changed since last call, 0 if not. Error 461 return codes are the same as \p driver_return_code_t 462 */ 463 int cdio_get_media_changed(CdIo_t *p_cdio); 464 465 /** True if CD-ROM understand ATAPI commands. */ 466 bool_3way_t cdio_have_atapi (CdIo_t *p_cdio); 467 468 /** Like cdio_have_xxx but uses an enumeration instead. */ 469 bool cdio_have_driver (driver_id_t driver_id); 470 471 /** 472 Free any resources associated with \p p_cdio. Call this when done 473 using p_cdio and using CD reading/control operations. 474 475 @param p_cdio the CD object to eliminated. 476 */ 477 void cdio_destroy (CdIo_t *p_cdio); 478 479 /** 480 Get a string decribing driver_id. 481 482 @param driver_id the driver you want the description for 483 @return a string of driver description 484 */ 485 const char *cdio_driver_describe (driver_id_t driver_id); 486 487 /** 488 Sets up to read from place specified by \p psz_source and 489 \p driver_id. This or cdio_open_* should be called before using any 490 other routine, except cdio_init or any routine that accesses the 491 CD-ROM drive by name. cdio_open will call cdio_init, if that 492 hasn't been done previously. 493 494 @return the cdio object or NULL on error or no device. If NULL 495 is given as the source, we'll use the default driver device. 496 */ 497 CdIo_t * cdio_open (const char *psz_source, driver_id_t driver_id); 498 499 /** 500 Sets up to read from place specified by psz_source, driver_id and 501 access mode. This or cdio_open* should be called before using any 502 other routine, except cdio_init or any routine that accesses the 503 CD-ROM drive by name. This will call cdio_init, if that hasn't 504 been done previously. 505 506 If \p NULL is given as the source, we'll use the default driver 507 device. 508 509 @return the cdio object or \p NULL on error or no device. 510 */ 511 CdIo_t * cdio_open_am (const char *psz_source, 512 driver_id_t driver_id, const char *psz_access_mode); 513 514 /** 515 Set up BIN/CUE CD disk-image for reading. Source is the .bin or 516 .cue file 517 518 @return the cdio object or \p NULL on error or no device. 519 */ 520 CdIo_t * cdio_open_bincue (const char *psz_cue_name); 521 522 /** 523 Set up BIN/CUE CD disk-image for reading. Source is the .bin or 524 .cue file 525 526 @return the cdio object or \p NULL on error or no device.. 527 */ 528 CdIo_t * cdio_open_am_bincue (const char *psz_cue_name, 529 const char *psz_access_mode); 530 531 /** 532 Set up cdrdao CD disk-image for reading. Source is the .toc file 533 534 @return the cdio object or \p NULL on error or no device. 535 */ 536 CdIo_t * cdio_open_cdrdao (const char *psz_toc_name); 537 538 /** 539 Set up cdrdao CD disk-image for reading. Source is the .toc file 540 541 @return the cdio object or NULL on error or no device.. 542 */ 543 CdIo_t * cdio_open_am_cdrdao (const char *psz_toc_name, 544 const char *psz_access_mode); 545 546 /** 547 Return a string containing the default CUE file that would 548 be used when none is specified. 549 550 @return the cdio object or \p NULL on error or no device. 551 */ 552 char * cdio_get_default_device_bincue(void); 553 554 char **cdio_get_devices_bincue(void); 555 556 /** 557 @return string containing the default CUE file that would be 558 used when none is specified. \p NULL is returned on error or there 559 is no device. 560 */ 561 char * cdio_get_default_device_cdrdao(void); 562 563 char **cdio_get_devices_cdrdao(void); 564 565 /** 566 Set up CD-ROM for reading. The device_name is 567 the some sort of device name. 568 569 @return the cdio object for subsequent operations. 570 \p NULL on error or there is no driver for a some sort of hardware CD-ROM. 571 */ 572 CdIo_t * cdio_open_cd (const char *device_name); 573 574 /** 575 Set up CD-ROM for reading. The device_name is 576 the some sort of device name. 577 578 @return the cdio object for subsequent operations. 579 \p NULL on error or there is no driver for a some sort of hardware CD-ROM. 580 */ 581 CdIo_t * cdio_open_am_cd (const char *psz_device, 582 const char *psz_access_mode); 583 584 /** 585 CDRWIN BIN/CUE CD disc-image routines. Source is the .cue file 586 587 @return the cdio object for subsequent operations. 588 \p NULL on error. 589 */ 590 CdIo_t * cdio_open_cue (const char *cue_name); 591 592 /** 593 Set up CD-ROM for reading using the AIX driver. The device_name is 594 the some sort of device name. 595 596 @return the cdio object for subsequent operations. 597 \p NULL on error or there is no AIX driver. 598 599 @see cdio_open() 600 */ 601 CdIo_t * cdio_open_am_aix (const char *psz_source, 602 const char *psz_access_mode); 603 604 /** 605 Set up CD-ROM for reading using the AIX driver. The device_name is 606 the some sort of device name. 607 608 @return the cdio object for subsequent operations. 609 \p NULL on error or there is no AIX driver. 610 611 @see cdio_open() 612 */ 613 CdIo_t * cdio_open_aix (const char *psz_source); 614 615 /** 616 Return a string containing the default device name that the AIX 617 driver would use when none is specified. 618 619 @return the cdio object for subsequent operations. 620 \p NULL on error or there is no AIX driver. 621 622 @see cdio_open_cd(), cdio_open() 623 */ 624 char * cdio_get_default_device_aix(void); 625 626 /** 627 Return a list of all of the CD-ROM devices that the AIX driver 628 can find. 629 630 In some situations of drivers or OS's we can't find a CD device 631 if there is no media in it and it is possible for this routine to 632 return \p NULL even though there may be a hardware CD-ROM. 633 */ 634 char **cdio_get_devices_aix(void); 635 636 /** 637 Set up CD-ROM for reading using the FreeBSD driver. The 638 device_name is the some sort of device name. 639 640 NULL is returned on error or there is no FreeBSD driver. 641 642 @see cdio_open_cd(), cdio_open() 643 */ 644 CdIo_t * cdio_open_freebsd (const char *paz_psz_source); 645 646 /** 647 Set up CD-ROM for reading using the FreeBSD driver. The 648 device_name is the some sort of device name. 649 650 NULL is returned on error or there is no FreeBSD driver. 651 652 @see cdio_open_cd(), cdio_open() 653 */ 654 CdIo_t * cdio_open_am_freebsd (const char *psz_source, 655 const char *psz_access_mode); 656 657 /** 658 Return a string containing the default device name that the 659 FreeBSD driver would use when none is specified. 660 661 NULL is returned on error or there is no CD-ROM device. 662 */ 663 char * cdio_get_default_device_freebsd(void); 664 665 /** 666 Return a list of all of the CD-ROM devices that the FreeBSD 667 driver can find. 668 */ 669 char **cdio_get_devices_freebsd(void); 670 671 /** 672 Set up CD-ROM for reading using the GNU/Linux driver. The 673 device_name is the some sort of device name. 674 675 @return the cdio object for subsequent operations. 676 NULL on error or there is no GNU/Linux driver. 677 678 In some situations of drivers or OS's we can't find a CD device if 679 there is no media in it and it is possible for this routine to return 680 NULL even though there may be a hardware CD-ROM. 681 */ 682 CdIo_t * cdio_open_linux (const char *psz_source); 683 684 /** 685 Set up CD-ROM for reading using the GNU/Linux driver. The 686 device_name is the some sort of device name. 687 688 @return the cdio object for subsequent operations. 689 NULL on error or there is no GNU/Linux driver. 690 */ 691 CdIo_t * cdio_open_am_linux (const char *psz_source, 692 const char *access_mode); 693 694 /** 695 Return a string containing the default device name that the 696 GNU/Linux driver would use when none is specified. A scan is made 697 for CD-ROM drives with CDs in them. 698 699 NULL is returned on error or there is no CD-ROM device. 700 701 In some situations of drivers or OS's we can't find a CD device if 702 there is no media in it and it is possible for this routine to return 703 NULL even though there may be a hardware CD-ROM. 704 705 @see cdio_open_cd, cdio_open 706 */ 707 char * cdio_get_default_device_linux(void); 708 709 /** 710 Return a list of all of the CD-ROM devices that the GNU/Linux 711 driver can find. 712 */ 713 char **cdio_get_devices_linux(void); 714 715 /** 716 Set up CD-ROM for reading using the Sun Solaris driver. The 717 device_name is the some sort of device name. 718 719 @return the cdio object for subsequent operations. 720 \p NULL on error or there is no Solaris driver. 721 */ 722 CdIo_t * cdio_open_solaris (const char *psz_source); 723 724 /** 725 Set up CD-ROM for reading using the Sun Solaris driver. The 726 device_name is the some sort of device name. 727 728 @return the cdio object for subsequent operations. 729 \p NULL on error or there is no Solaris driver. 730 */ 731 CdIo_t * cdio_open_am_solaris (const char *psz_source, 732 const char *psz_access_mode); 733 734 /** 735 Return a string containing the default device name that the 736 Solaris driver would use when none is specified. A scan is made 737 for CD-ROM drives with CDs in them. 738 739 \p NULL is returned on error or there is no CD-ROM device. 740 741 In some situations of drivers or OS's we can't find a CD device if 742 there is no media in it and it is possible for this routine to return 743 \p NULL even though there may be a hardware CD-ROM. 744 745 @see cdio_open_cd(), cdio_open() 746 */ 747 char * cdio_get_default_device_solaris(void); 748 749 /** 750 Return a list of all of the CD-ROM devices that the Solaris 751 driver can find. 752 */ 753 char **cdio_get_devices_solaris(void); 754 755 /** 756 Set up CD-ROM for reading using the Apple OSX driver. The 757 device_name is the some sort of device name. 758 759 \p NULL is returned on error or there is no OSX driver. 760 761 In some situations of drivers or OS's we can't find a CD device if 762 there is no media in it and it is possible for this routine to return 763 NULL even though there may be a hardware CD-ROM. 764 765 @see cdio_open_cd(), cdio_open() 766 */ 767 CdIo_t * cdio_open_osx (const char *psz_source); 768 769 /** 770 Set up CD-ROM for reading using the Apple OSX driver. The 771 device_name is the some sort of device name. 772 773 NULL is returned on error or there is no OSX driver. 774 775 @see cdio_open_cd(), cdio_open() 776 */ 777 CdIo_t * cdio_open_am_osx (const char *psz_source, 778 const char *psz_access_mode); 779 780 /** 781 Return a string containing the default device name that the OSX 782 driver would use when none is specified. A scan is made for 783 CD-ROM drives with CDs in them. 784 785 In some situations of drivers or OS's we can't find a CD device if 786 there is no media in it and it is possible for this routine to return 787 NULL even though there may be a hardware CD-ROM. 788 */ 789 char * cdio_get_default_device_osx(void); 790 791 /** 792 Return a list of all of the CD-ROM devices that the OSX driver 793 can find. 794 */ 795 char **cdio_get_devices_osx(void); 796 797 /** 798 Set up CD-ROM for reading using the Microsoft Windows driver. The 799 device_name is the some sort of device name. 800 801 In some situations of drivers or OS's we can't find a CD device if 802 there is no media in it and it is possible for this routine to return 803 NULL even though there may be a hardware CD-ROM. 804 */ 805 CdIo_t * cdio_open_win32 (const char *psz_source); 806 807 /** 808 Set up CD-ROM for reading using the Microsoft Windows driver. The 809 device_name is the some sort of device name. 810 811 NULL is returned on error or there is no Microsof Windows driver. 812 */ 813 CdIo_t * cdio_open_am_win32 (const char *psz_source, 814 const char *psz_access_mode); 815 816 /** 817 Return a string containing the default device name that the 818 Win32 driver would use when none is specified. A scan is made 819 for CD-ROM drives with CDs in them. 820 821 In some situations of drivers or OS's we can't find a CD device 822 if there is no media in it and it is possible for this routine to 823 return NULL even though there may be a hardware CD-ROM. 824 825 @see cdio_open_cd(), cdio_open() 826 */ 827 char * cdio_get_default_device_win32(void); 828 829 char **cdio_get_devices_win32(void); 830 831 /** 832 Set up CD-ROM for reading using the Nero driver. The device_name 833 is the some sort of device name. 834 835 @return true on success; NULL on error or there is no Nero driver. 836 */ 837 CdIo_t * cdio_open_nrg (const char *psz_source); 838 839 /** 840 Set up CD-ROM for reading using the Nero driver. The device_name 841 is the some sort of device name. 842 843 @return true on success; NULL on error or there is no Nero driver. 844 */ 845 CdIo_t * cdio_open_am_nrg (const char *psz_source, 846 const char *psz_access_mode); 847 848 /** 849 Get a string containing the default device name that the NRG 850 driver would use when none is specified. A scan is made for NRG 851 disk images in the current directory. 852 853 @return string containing the default device. NULL on error or 854 there is no CD-ROM device. 855 */ 856 char * cdio_get_default_device_nrg(void); 857 858 char **cdio_get_devices_nrg(void); 859 860 /** 861 862 Determine if bin_name is the bin file part of a CDRWIN CD disk image. 863 864 @param bin_name location of presumed CDRWIN bin image file. 865 @return the corresponding CUE file if bin_name is a BIN file or 866 \p NULL if not a BIN file. 867 */ 868 char *cdio_is_binfile(const char *bin_name); 869 870 /** 871 Determine if cue_name is the cue sheet for a CDRWIN CD disk image. 872 873 @return corresponding BIN file if cue_name is a CDRWIN cue file or 874 \p NULL if not a CUE file. 875 */ 876 char *cdio_is_cuefile(const char *cue_name); 877 878 /** 879 Determine if psg_nrg is a Nero CD disc image. 880 881 @param psz_nrg location of presumed NRG image file. 882 @return true if psz_nrg is a Nero NRG image or false 883 if not a NRG image. 884 */ 885 bool cdio_is_nrg(const char *psz_nrg); 886 887 /** 888 Determine if psz_toc is a TOC file for a cdrdao CD disc image. 889 890 @param psz_toc location of presumed TOC image file. 891 @return true if toc_name is a cdrdao TOC file or false 892 if not a TOC file. 893 */ 894 bool cdio_is_tocfile(const char *psz_toc); 895 896 /** 897 Determine if psz_source refers to a real hardware CD-ROM. 898 899 @param psz_source location name of object 900 @param driver_id driver for reading object. Use DRIVER_UNKNOWN if you 901 don't know what driver to use. 902 @return true if psz_source is a device; If false is returned we 903 could have a CD disk image. 904 */ 905 bool cdio_is_device(const char *psz_source, driver_id_t driver_id); 906 907 /** 908 Set the blocksize for subsequent reads. 909 */ 910 driver_return_code_t cdio_set_blocksize ( const CdIo_t *p_cdio, 911 int i_blocksize ); 912 913 /** 914 Set the drive speed. 915 916 @param p_cdio CD structure set by cdio_open(). 917 918 @param i_drive_speed speed in CD-ROM speed units. Note this not 919 Kbs as would be used in the MMC spec or in 920 mmc_set_speed(). To convert CD-ROM speed 921 units to Kbs, multiply the number by 176 (for 922 raw data) and by 150 (for filesystem 923 data). On many CD-ROM drives, specifying a 924 value too large will result in using the 925 fastest speed. 926 927 @see mmc_set_speed() and mmc_set_drive_speed() 928 */ 929 driver_return_code_t cdio_set_speed ( const CdIo_t *p_cdio, 930 int i_drive_speed ); 931 932 /** 933 Get the value associatied with key. 934 935 @param p_cdio the CD object queried @param key the key to 936 retrieve @return the value associated with "key", \p NULL if \p 937 p_cdio is \p NULL, or "key" does not exist. 938 */ 939 const char * cdio_get_arg (const CdIo_t *p_cdio, const char key[]); 940 941 /** 942 Set the arg "key" with "value" in "p_cdio". 943 944 @param p_cdio the CD object to set 945 @param key the key to set 946 @param value the value to assocaiate with key 947 */ 948 driver_return_code_t cdio_set_arg (CdIo_t *p_cdio, const char key[], 949 const char value[]); 950 951 /** 952 Initialize CD Reading and control routines. Should be called first. 953 */ 954 bool cdio_init(void); 955 956 #ifdef __cplusplus 957 } 958 #endif /* __cplusplus */ 959 960 /** 961 The below variables are trickery to force the above enum symbol 962 values to be recorded in debug symbol tables. They are used to 963 allow one to refer to the enumeration value names in the typedefs 964 above in a debugger and debugger expressions. */ 965 extern cdio_drive_cap_misc_t debug_cdio_drive_cap_misc; 966 extern cdio_drive_cap_read_t debug_cdio_drive_cap_read_t; 967 extern cdio_drive_cap_write_t debug_drive_cap_write_t; 968 extern cdio_mmc_hw_len_t debug_cdio_mmc_hw_len; 969 extern cdio_src_category_mask_t debug_cdio_src_category_mask; 970 971 #endif /* CDIO_DEVICE_H_ */ 972