diff --git a/include/cdio/cdio.h b/include/cdio/cdio.h index e4f26987..45ca6094 100644 --- a/include/cdio/cdio.h +++ b/include/cdio/cdio.h @@ -1,5 +1,5 @@ /* -*- c -*- - $Id: cdio.h,v 1.32 2003/11/04 12:28:08 rocky Exp $ + $Id: cdio.h,v 1.33 2003/11/05 12:40:34 rocky Exp $ Copyright (C) 2001 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -19,7 +19,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* Public CD Input and Control Interface . */ +/** \file cdio.h - Public CD Input and Control Interface . */ #ifndef __CDIO_H__ @@ -56,7 +56,7 @@ extern "C" { /** This is an opaque structure. */ typedef struct _CdIo CdIo; - /** The below enumerations may be used to tag a specific driver + /** The driver_id_t enumerations may be used to tag a specific driver * that is opened or is desired to be opened. Note that this is * different than what is available on a given host. * @@ -86,7 +86,7 @@ extern "C" { /** Make sure what's listed for CDIO_MIN_DRIVER is the last enumeration in driver_id_t. Since we have a bogus (but useful) 0th - entry above we don't have to add one below. + entry above we don't have to add one. */ #define CDIO_MIN_DRIVER DRIVER_BSDI #define CDIO_MIN_DEVICE_DRIVER CDIO_MIN_DRIVER @@ -318,16 +318,32 @@ extern "C" { /* True if xxx driver is available. where xxx=linux, solaris, nrg, ... */ + + /*! True if BSDI driver is available. */ bool cdio_have_bsdi (void); + + /*! True if FreeBSD driver is available. */ bool cdio_have_freebsd (void); + + /*! True if GNU/Linux driver is available. */ bool cdio_have_linux (void); + + /*! True if Sun Solaris driver is available. */ bool cdio_have_solaris (void); + + /*! True if Apple OSX driver is available. */ bool cdio_have_osx (void); + + /*! True if Microsoft Windows driver is available. */ bool cdio_have_win32 (void); + + /*! True if Nero driver is available. */ bool cdio_have_nrg (void); + + /*! True if BIN/CUE driver is available. */ bool cdio_have_bincue (void); - /* Like above but uses the enumeration instead. */ + /*! Like cdio_have_xxx but uses an enumeration instead. */ bool cdio_have_driver (driver_id_t driver_id); /*! Return a string decribing driver_id. */ @@ -336,23 +352,31 @@ extern "C" { /*! Sets up to read from place specified by source_name and driver_id This should be called before using any other routine, except cdio_init. This will call cdio_init, if that hasn't been - done previously. to call one of the specific routines below. + done previously. to call one of the specific cdio_open_xxx + routines. NULL is returned on error. */ CdIo * cdio_open (const char *source_name, driver_id_t driver_id); - /*! cdrao BIN/CUE CD disk-image routines. Source is the .bin file + /*! Set up BIN/CUE CD disk-image for reading. Source is the .bin or + .cue file NULL is returned on error. */ CdIo * cdio_open_bincue (const char *bin_name); + /*! Return a string containing the default CUE file that would + be used when none is specified. + + NULL is returned on error or there is no device. + */ char * cdio_get_default_device_bincue(void); char **cdio_get_devices_bincue(void); - /*! CD routines. Source is the some sort of device. + /*! Set up CD-ROM for reading. The device_name is + the some sort of device name. NULL is returned on error. */ @@ -364,65 +388,131 @@ extern "C" { */ CdIo * cdio_open_cue (const char *cue_name); - /*! BSDI CD-reading routines. - NULL is returned on error. - */ + /*! Set up CD-ROM for reading using the BSDI driver. The device_name is + the some sort of device name. + + NULL is returned on error or there is no BSDI driver. + */ CdIo * cdio_open_bsdi (const char *source_name); + /*! Return a string containing the default device name that the + BSDI driver would use when none is specified. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_bsdi(void); char **cdio_get_devices_bsdi(void); - /*! BSDI CD-reading routines. - NULL is returned on error. - */ + /*! Set up CD-ROM for reading using the FreeBSD driver. The device_name is + the some sort of device name. + + NULL is returned on error or there is no FreeBSD driver. + */ CdIo * cdio_open_freebsd (const char *source_name); + /*! Return a string containing the default device name that the + FreeBSD driver would use when none is specified. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_freebsd(void); + /*! Return a list of all of the CD-ROM devices that the FreeBSD driver + can find. + */ char **cdio_get_devices_freebsd(void); - /*! Linux CD-reading routines. - NULL is returned on error. + /*! Set up CD-ROM for reading using the GNU/Linux driver. The device_name is + the some sort of device name. + + NULL is returned on error or there is no GNU/Linux driver. */ CdIo * cdio_open_linux (const char *source_name); + /*! Return a string containing the default device name that the + GNU/Linux driver would use when none is specified. A scan is made + for CD-ROM drives with CDs in them. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_linux(void); + /*! Return a list of all of the CD-ROM devices that the GNU/Linux driver + can find. + */ char **cdio_get_devices_linux(void); - /*! Solaris CD-reading routines. - NULL is returned on error. + /*! Set up CD-ROM for reading using the Sun Solaris driver. The + device_name is the some sort of device name. + + NULL is returned on error or there is no Solaris driver. */ CdIo * cdio_open_solaris (const char *source_name); + /*! Return a string containing the default device name that the + Solaris driver would use when none is specified. A scan is made + for CD-ROM drives with CDs in them. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_solaris(void); + /*! Return a list of all of the CD-ROM devices that the Solaris driver + can find. + */ char **cdio_get_devices_solaris(void); - /*! Darwin OS X CD-reading routines. - NULL is returned on error. + /*! Set up CD-ROM for reading using the Apple OSX driver. The + device_name is the some sort of device name. + + NULL is returned on error or there is no OSX driver. */ CdIo * cdio_open_osx (const char *source_name); + /*! Return a string containing the default device name that the + OSX driver would use when none is specified. A scan is made + for CD-ROM drives with CDs in them. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_osx(void); + /*! Return a list of all of the CD-ROM devices that the OSX driver + can find. + */ char **cdio_get_devices_osx(void); - /*! Win32 CD-reading routines. - NULL is returned on error. + /*! Set up CD-ROM for reading using the Microsoft Windows driver. The + device_name is the some sort of device name. + + NULL is returned on error or there is no Microsof Windows driver. */ CdIo * cdio_open_win32 (const char *source_name); + /*! Return a string containing the default device name that the + Win32 driver would use when none is specified. A scan is made + for CD-ROM drives with CDs in them. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_win32(void); char **cdio_get_devices_win32(void); - /*! Nero CD disk-image routines. - NULL is returned on error. + /*! Set up CD-ROM for reading using the Nero driver. The + device_name is the some sort of device name. + + NULL is returned on error or there is no Nero driver. */ CdIo * cdio_open_nrg (const char *source_name); + /*! Return a string containing the default device name that the + NRG driver would use when none is specified. A scan is made + for NRG disk images in the current directory.. + + NULL is returned on error or there is no CD-ROM device + */ char * cdio_get_default_device_nrg(void); char **cdio_get_devices_nrg(void); diff --git a/include/cdio/iso9660.h b/include/cdio/iso9660.h index 4f673e01..828bb00c 100644 --- a/include/cdio/iso9660.h +++ b/include/cdio/iso9660.h @@ -1,5 +1,5 @@ /* - $Id: iso9660.h,v 1.27 2003/11/04 04:45:24 rocky Exp $ + $Id: iso9660.h,v 1.28 2003/11/05 12:40:35 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -23,9 +23,9 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* - * Header file iso9660.h - assorted structure definitions and typecasts. - specific to iso9660 filesystem. +/*! + * \file iso9660.h - Assorted structure definitions and typecasts. + * specific for the ISO 9660 filesystem. */ @@ -42,16 +42,19 @@ #define MIN_TRACK_SIZE 4*75 #define MIN_ISO_SIZE MIN_TRACK_SIZE -/* - A ISO filename is: "abcde.eee;1" -> '.' ';' - +/*! + An ISO filename is: "abcde.eee;1" -> '.' ';' + The maximum needed string length is: + +\verbatim 30 chars (filename + ext) + 2 chars ('.' + ';') + strlen("32767") + null byte ================================ = 38 chars +\endverbatim */ #define LEN_ISONAME 31 #define MAX_ISONAME 37 @@ -61,26 +64,28 @@ /* * ISO 9660 directory flags. */ -#define ISO_FILE 0 /* Not really a flag... */ -#define ISO_EXISTENCE 1 /* Do not make existence known (hidden) */ -#define ISO_DIRECTORY 2 /* This file is a directory */ -#define ISO_ASSOCIATED 4 /* This file is an assiciated file */ -#define ISO_RECORD 8 /* Record format in extended attr. != 0 */ -#define ISO_PROTECTION 16 /* No read/execute perm. in ext. attr. */ -#define ISO_DRESERVED1 32 /* Reserved bit 5 */ -#define ISO_DRESERVED2 64 /* Reserved bit 6 */ -#define ISO_MULTIEXTENT 128 /* Not final entry of a mult. ext. file */ +#define ISO_FILE 0 /**< Not really a flag... */ +#define ISO_EXISTENCE 1 /**< Do not make existence known (hidden) */ +#define ISO_DIRECTORY 2 /**< This file is a directory */ +#define ISO_ASSOCIATED 4 /**< This file is an associated file */ +#define ISO_RECORD 8 /**< Record format in extended attr. != 0 */ +#define ISO_PROTECTION 16 /**< No read/execute perm. in ext. attr. */ +#define ISO_DRESERVED1 32 /**< Reserved bit 5 */ +#define ISO_DRESERVED2 64 /**< Reserved bit 6 */ +#define ISO_MULTIEXTENT 128 /**< Not final entry of a mult. ext. file */ /* Volume descriptor types */ #define ISO_VD_PRIMARY 1 -#define ISO_VD_SUPPLEMENTARY 2 /* Used by Joliet */ +#define ISO_VD_SUPPLEMENTARY 2 /**< Used by Joliet */ #define ISO_VD_END 255 -#define ISO_PVD_SECTOR 16 /* Sector of Primary Volume Descriptor */ -#define ISO_EVD_SECTOR 17 /* Sector of End Volume Descriptor */ +#define ISO_PVD_SECTOR 16 /**< Sector of Primary Volume Descriptor */ +#define ISO_EVD_SECTOR 17 /**< Sector of End Volume Descriptor */ -#define ISO_STANDARD_ID "CD001" -#define ISO_BLOCKSIZE 2048 +#define ISO_STANDARD_ID "CD001" /**< String inside track identifiying an + ISO 9660 filesystem. */ +#define ISO_BLOCKSIZE 2048 /**< Number of bytes in an ISO + 9660 block */ #ifdef __cplusplus extern "C" { @@ -97,12 +102,14 @@ PRAGMA_BEGIN_PACKED struct iso9660_dtime { uint8_t dt_year; - uint8_t dt_month; /* 1..12. Note 1 origin not 0, like a tm struct. */ + uint8_t dt_month; /**< Has value in range 1..12. Note starts + at 1, not 0 like a tm struct. */ uint8_t dt_day; uint8_t dt_hour; uint8_t dt_minute; uint8_t dt_second; - int8_t dt_gmtoff; /* GMT values -48 .. + 52 in 15 min intervals */ + int8_t dt_gmtoff; /**< GMT values -48 .. + 52 in 15 minute + intervals */ } GNUC_PACKED; typedef struct iso9660_dtime iso9660_dtime_t; @@ -110,13 +117,20 @@ typedef struct iso9660_dtime iso9660_dtime_t; /*! ISO-9660 Primary Volume Descriptor. */ struct iso9660_ltime { - char lt_year [_delta( 1, 4)]; /*! Add 1900 for Julian year */ - char lt_month [_delta( 5, 6)]; /*! 1..12. Note starts at 1. */ + char lt_year [_delta( 1, 4)]; /**< Add 1900 to value + for the Julian + year */ + char lt_month [_delta( 5, 6)]; /**< Has value in range + 1..12. Note starts + at 1, not 0 like a + tm struct. */ char lt_day [_delta( 7, 8)]; char lt_hour [_delta( 9, 10)]; char lt_minute [_delta( 11, 12)]; char lt_second [_delta( 13, 14)]; - char lt_hsecond [_delta( 15, 16)]; /*! 1/100's of a second */ + char lt_hsecond [_delta( 15, 16)]; /** Copyright (C) 2003 Rocky Bernstein @@ -18,8 +18,44 @@ along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* - Things related to CDROM layout. Sector sizes, MSFs, LBAs, +/*! + \file sector.h - Things related to CDROM layout. Sector sizes, + MSFs, LBAs, + + A CD-ROM physical sector size is 2048, 2052, 2056, 2324, 2332, 2336, + 2340, or 2352 bytes long. + + Sector types of the standard CD-ROM data formats: + +\verbatim + format sector type user data size (bytes) + ----------------------------------------------------------------------------- + 1 (Red Book) CD-DA 2352 (CDIO_CD_FRAMESIZE_RAW) + 2 (Yellow Book) Mode1 Form1 2048 (CDIO_CD_FRAMESIZE) + 3 (Yellow Book) Mode1 Form2 2336 (M2RAW_SECTOR_SIZE) + 4 (Green Book) Mode2 Form1 2048 (CDIO_CD_FRAMESIZE) + 5 (Green Book) Mode2 Form2 2328 (2324+4 spare bytes) + + + The layout of the standard CD-ROM data formats: + ----------------------------------------------------------------------------- + - audio (red): | audio_sample_bytes | + | 2352 | + + - data (yellow, mode1): | sync - head - data - EDC - zero - ECC | + | 12 - 4 - 2048 - 4 - 8 - 276 | + + - data (yellow, mode2): | sync - head - data | + | 12 - 4 - 2336 | + + - XA data (green, mode2 form1): | sync - head - sub - data - EDC - ECC | + | 12 - 4 - 8 - 2048 - 4 - 276 | + + - XA data (green, mode2 form2): | sync - head - sub - data - Spare | + | 12 - 4 - 8 - 2324 - 4 | +\endverbatim + + */ #ifndef _CDIO_SECTOR_H_ @@ -34,80 +70,50 @@ #define CDIO_PREGAP_SECTORS 150 #define CDIO_POSTGAP_SECTORS 150 -/* - * A CD-ROM physical sector size is 2048, 2052, 2056, 2324, 2332, 2336, - * 2340, or 2352 bytes long. - -* Sector types of the standard CD-ROM data formats: - * - * format sector type user data size (bytes) - * ----------------------------------------------------------------------------- - * 1 (Red Book) CD-DA 2352 (CDIO_CD_FRAMESIZE_RAW) - * 2 (Yellow Book) Mode1 Form1 2048 (CDIO_CD_FRAMESIZE) - * 3 (Yellow Book) Mode1 Form2 2336 (M2RAW_SECTOR_SIZE) - * 4 (Green Book) Mode2 Form1 2048 (CDIO_CD_FRAMESIZE) - * 5 (Green Book) Mode2 Form2 2328 (2324+4 spare bytes) - * - * - * The layout of the standard CD-ROM data formats: - * ----------------------------------------------------------------------------- - * - audio (red): | audio_sample_bytes | - * | 2352 | - * - * - data (yellow, mode1): | sync - head - data - EDC - zero - ECC | - * | 12 - 4 - 2048 - 4 - 8 - 276 | - * - * - data (yellow, mode2): | sync - head - data | - * | 12 - 4 - 2336 | - * - * - XA data (green, mode2 form1): | sync - head - sub - data - EDC - ECC | - * | 12 - 4 - 8 - 2048 - 4 - 276 | - * - * - XA data (green, mode2 form2): | sync - head - sub - data - Spare | - * | 12 - 4 - 8 - 2324 - 4 | - * - */ - /* Some generally useful CD-ROM information -- mostly based on the above. This is from linux.h - not to slight other OS's. This was the first place I came across such useful stuff. */ -#define CDIO_CD_MINS 74 /* max. minutes per CD, not really a limit */ -#define CDIO_CD_SECS_PER_MIN 60 /* seconds per minute */ -#define CDIO_CD_FRAMES_PER_SEC 75 /* frames per second */ -#define CDIO_CD_SYNC_SIZE 12 /* 12 sync bytes per raw data frame */ -#define CDIO_CD_CHUNK_SIZE 24 /* lowest-level "data bytes piece" */ -#define CDIO_CD_NUM_OF_CHUNKS 98 /* chunks per frame */ -#define CDIO_CD_FRAMESIZE_SUB 96 /* subchannel data "frame" size */ -#define CDIO_CD_HEADER_SIZE 4 /* header (address) bytes per raw data - frame */ -#define CDIO_CD_SUBHEADER_SIZE 8 /* subheader bytes per raw XA data frame */ -#define CDIO_CD_EDC_SIZE 4 /* bytes EDC per most raw data frame types */ -#define CDIO_CD_M1F1_ZERO_SIZE 8 /* bytes zero per yellow book mode 1 frame */ -#define CDIO_CD_ECC_SIZE 276 /* bytes ECC per most raw data frame types */ -#define CDIO_CD_FRAMESIZE 2048 /* bytes per frame, "cooked" mode */ -#define CDIO_CD_FRAMESIZE_RAW 2352/* bytes per frame, "raw" mode */ -#define CDIO_CD_FRAMESIZE_RAWER 2646 /* The maximum possible returned bytes */ +#define CDIO_CD_MINS 74 /**< max. minutes per CD, not really + a limit */ +#define CDIO_CD_SECS_PER_MIN 60 /**< seconds per minute */ +#define CDIO_CD_FRAMES_PER_SEC 75 /**< frames per second */ +#define CDIO_CD_SYNC_SIZE 12 /**< 12 sync bytes per raw data frame */ +#define CDIO_CD_CHUNK_SIZE 24 /**< lowest-level "data bytes piece" */ +#define CDIO_CD_NUM_OF_CHUNKS 98 /**< chunks per frame */ +#define CDIO_CD_FRAMESIZE_SUB 96 /**< subchannel data "frame" size */ +#define CDIO_CD_HEADER_SIZE 4 /**< header (address) bytes per raw + data frame */ +#define CDIO_CD_SUBHEADER_SIZE 8 /**< subheader bytes per raw XA data frame */ +#define CDIO_CD_EDC_SIZE 4 /**< bytes EDC per most raw data + frame types */ +#define CDIO_CD_M1F1_ZERO_SIZE 8 /**< bytes zero per yellow book mode + 1 frame */ +#define CDIO_CD_ECC_SIZE 276 /**< bytes ECC per most raw data frame types */ +#define CDIO_CD_FRAMESIZE 2048 /**< bytes per frame, "cooked" mode */ +#define CDIO_CD_FRAMESIZE_RAW 2352/**< bytes per frame, "raw" mode */ +#define CDIO_CD_FRAMESIZE_RAWER 2646 /**< The maximum possible returned bytes */ #define CDIO_CD_FRAMESIZE_RAW1 (CDIO_CD_CD_FRAMESIZE_RAW-CDIO_CD_SYNC_SIZE) /*2340*/ #define CDIO_CD_FRAMESIZE_RAW0 (CDIO_CD_FRAMESIZE_RAW-CDIO_CD_SYNC_SIZE-CDIO_CD__HEAD_SIZE) /*2336*/ -/* "before data" part of raw XA (green, mode2) frame */ +/*! "before data" part of raw XA (green, mode2) frame */ #define CDIO_CD_XA_HEADER (CDIO_CD_HEADER_SIZE+CDIO_CD_SUBHEADER_SIZE) -/* "after data" part of raw XA (green, mode2 form1) frame */ +/*! "after data" part of raw XA (green, mode2 form1) frame */ #define CDIO_CD_XA_TAIL (CDIO_CD_EDC_SIZE+CDIO_CD_ECC_SIZE) -/* "before data" sync bytes + header of XA (green, mode2) frame */ +/*! "before data" sync bytes + header of XA (green, mode2) frame */ #define CDIO_CD_XA_SYNC_HEADER (CDIO_CD_SYNC_SIZE+CDIO_CD_XA_HEADER) /* CD-ROM address types (Linux cdrom_tocentry.cdte_format) */ -#define CDIO_CDROM_LBA 0x01 /* "logical block": first frame is #0 */ -#define CDIO_CDROM_MSF 0x02 /* "minute-second-frame": binary, not bcd here! */ +#define CDIO_CDROM_LBA 0x01 /**< "logical block": first frame is #0 */ +#define CDIO_CDROM_MSF 0x02 /**< "minute-second-frame": binary, not + BCD here! */ #define CDIO_CDROM_DATA_TRACK 0x04 -/* The leadout track is always 0xAA, regardless of # of tracks on disc */ +/*! The leadout track is always 0xAA, regardless of # of tracks on disc */ #define CDIO_CDROM_LEADOUT_TRACK 0xAA #define M2F2_SECTOR_SIZE 2324 @@ -129,20 +135,40 @@ #define msf_t_SIZEOF 3 -/* warning, returns new allocated string */ +/*! + Convert an LBA into a string representation of the MSF. + \warning cdio_lba_to_msf_str returns new allocated string */ char *cdio_lba_to_msf_str (lba_t lba); +/*! + Convert an LBA into the corresponding LSN. +*/ lba_t cdio_lba_to_lsn (lba_t lba); +/*! + Convert an LBA into the corresponding MSF. +*/ void cdio_lba_to_msf(lba_t lba, msf_t *msf); +/*! + Convert an LSN into the corresponding LBA. +*/ lba_t cdio_lsn_to_lba (lsn_t lsn); +/*! + Convert an LSN into the corresponding MSF. +*/ void cdio_lsn_to_msf (lsn_t lsn, msf_t *msf); +/*! + Convert a MSF into the corresponding LBA. +*/ lba_t cdio_msf_to_lba (const msf_t *msf); +/*! + Convert a MSF into the corresponding LSN. +*/ lsn_t cdio_msf_to_lsn (const msf_t *msf);