diff options
Diffstat (limited to 'src/input/vcd/libcdio/cdio/cdio.h')
| -rw-r--r-- | src/input/vcd/libcdio/cdio/cdio.h | 299 |
1 files changed, 210 insertions, 89 deletions
diff --git a/src/input/vcd/libcdio/cdio/cdio.h b/src/input/vcd/libcdio/cdio/cdio.h index d0b304b38..a9fa4b02e 100644 --- a/src/input/vcd/libcdio/cdio/cdio.h +++ b/src/input/vcd/libcdio/cdio/cdio.h @@ -1,8 +1,8 @@ /* -*- c -*- - $Id: cdio.h,v 1.1 2003/10/13 11:47:12 f1rmb Exp $ + $Id: cdio.h,v 1.2 2004/04/11 12:20:31 miguelfreitas Exp $ Copyright (C) 2001 Herbert Valerio Riedel <hvr@gnu.org> - Copyright (C) 2003 Rocky Bernstein <rocky@panix.com> + Copyright (C) 2003, 2004 Rocky Bernstein <rocky@panix.com> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -19,14 +19,16 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* Public CD Input and Control Interface . */ +/** \file cdio.h + * \brief The top-level header for libcdio: the CD Input and Control library. + */ #ifndef __CDIO_H__ #define __CDIO_H__ -/* Application Interface or Protocol version number. If the public - interface changes, we increase this number. +/** Application Interface or Protocol version number. If the public + * interface changes, we increase this number. */ #define CDIO_API_VERSION 1 @@ -43,64 +45,68 @@ #include <cdio/sector.h> /* Flags specifying the category of device to open or is opened. */ -#define CDIO_SRC_IS_DISK_IMAGE_MASK 0x0001 -#define CDIO_SRC_IS_DEVICE_MASK 0x0002 -#define CDIO_SRC_IS_SCSI_MASK 0x0004 + +#define CDIO_SRC_IS_DISK_IMAGE_MASK 0x0001 /**< Read source is a CD image. */ +#define CDIO_SRC_IS_DEVICE_MASK 0x0002 /**< Read source is a CD device. */ +#define CDIO_SRC_IS_SCSI_MASK 0x0004 #define CDIO_SRC_IS_NATIVE_MASK 0x0008 #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ - /* opaque structure */ + /** This is an opaque structure. */ typedef struct _CdIo CdIo; - /* The below 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. - - Order is a little significant since the order is used in scans. - We have to start with UNKNOWN and devices should come before - disk-image readers. By putting something towards the top (a lower - enumeration number), in an iterative scan we prefer that to something - with a higher enumeration number. - - NOTE: IF YOU MODIFY ENUM MAKE SURE INITIALIZATION IN CDIO.C AGREES. - - */ + /** 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. + * + * Order is a little significant since the order is used in scans. + * We have to start with UNKNOWN and devices should come before + * disk-image readers. By putting something towards the top (a lower + * enumeration number), in an iterative scan we prefer that to + * something with a higher enumeration number. + * + * NOTE: IF YOU MODIFY ENUM MAKE SURE INITIALIZATION IN CDIO.C AGREES. + * + */ typedef enum { DRIVER_UNKNOWN, - DRIVER_BSDI, - DRIVER_FREEBSD, - DRIVER_LINUX, - DRIVER_SOLARIS, - DRIVER_OSX, - DRIVER_WIN32, - DRIVER_BINCUE, /* Prefer bincue over nrg when both exist */ - DRIVER_NRG, - DRIVER_DEVICE /* Is really a set of the above; should come last */ + DRIVER_BSDI, /**< BSDI driver */ + DRIVER_FREEBSD, /**< FreeBSD driver */ + DRIVER_LINUX, /**< GNU/Linux Driver */ + DRIVER_SOLARIS, /**< Sun Solaris Driver */ + DRIVER_OSX, /**< Apple OSX Driver */ + DRIVER_WIN32, /**< Microsoft Windows Driver */ + DRIVER_BINCUE, /**< BIN/CUE format CD image. This is listed before NRG, + to make the code prefer BINCUE over NRG when both + exist. */ + DRIVER_NRG, /**< Nero NRG format CD image. */ + DRIVER_DEVICE /**< Is really a set of the above; should come last */ } driver_id_t; - /* Make sure what's listed below is the last one above. Since we have - a bogus (but useful) 0th entry above we don't have to add one below. - */ +/** 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. +*/ #define CDIO_MIN_DRIVER DRIVER_BSDI #define CDIO_MIN_DEVICE_DRIVER CDIO_MIN_DRIVER #define CDIO_MAX_DRIVER DRIVER_NRG #define CDIO_MAX_DEVICE_DRIVER DRIVER_WIN32 typedef enum { - TRACK_FORMAT_AUDIO, /* Audio track, e.g. CD-DA */ - TRACK_FORMAT_CDI, /* CD-i. How this is different from DATA below? */ - TRACK_FORMAT_XA, /* Mode2 of some sort */ - TRACK_FORMAT_DATA, /* Mode1 of some sort */ - TRACK_FORMAT_PSX, /* Playstation CD. Like audio but only 2336 bytes - of user data. + TRACK_FORMAT_AUDIO, /**< Audio track, e.g. CD-DA */ + TRACK_FORMAT_CDI, /**< CD-i. How this is different from DATA below? */ + TRACK_FORMAT_XA, /**< Mode2 of some sort */ + TRACK_FORMAT_DATA, /**< Mode1 of some sort */ + TRACK_FORMAT_PSX, /**< Playstation CD. Like audio but only 2336 bytes + * of user data. */ - TRACK_FORMAT_ERROR /* Dunno what is or some other error. */ + TRACK_FORMAT_ERROR /**< Dunno what is, or some other error. */ } track_format_t; - /* Printable tags for above enumeration. */ + /*! Printable tags for track_format_t enumeration. */ extern const char *track_format2str[6]; /*! @@ -140,12 +146,14 @@ extern "C" { To find a CD-drive of any type, use the mask CDIO_FS_MATCH_ALL. NULL is returned if we couldn't get a default device. + It is also possible to return a non NULL but after dereferencing the + the value is NULL. This also means nothing was found. */ char ** cdio_get_devices_with_cap (char* search_devices[], cdio_fs_anal_t capabilities, bool any); - /*!Return an array of device names. If you want a specific - devices, dor a driver give that device, if you want hardware + /*! Return an array of device names. If you want a specific + devices for a driver, give that device. If you want hardware devices, give DRIVER_DEVICE and if you want all possible devices, image drivers and hardware drivers give DRIVER_UNKNOWN. @@ -190,7 +198,7 @@ extern "C" { track_t cdio_get_num_tracks (const CdIo *obj); /*! - Get format of track. + Get the format (audio, mode2, mode1) of track. */ track_format_t cdio_get_track_format(const CdIo *obj, track_t track_num); @@ -255,46 +263,46 @@ extern "C" { ssize_t cdio_read(const CdIo *obj, void *buf, size_t size); /*! - Reads a audio sector from cd device into data starting - from lsn. Returns 0 if no error. - */ + Reads a audio sector from cd device into data starting + from lsn. Returns 0 if no error. + */ int cdio_read_audio_sector (const CdIo *obj, void *buf, lsn_t lsn); /*! - Reads a audio sector from cd device into data starting - from lsn. Returns 0 if no error. - */ + Reads a audio sector from cd device into data starting + from lsn. Returns 0 if no error. + */ int cdio_read_audio_sectors (const CdIo *obj, void *buf, lsn_t lsn, unsigned int nblocks); /*! Reads a single mode1 sector from cd device into data starting from lsn. Returns 0 if no error. - */ + */ int cdio_read_mode1_sector (const CdIo *obj, void *buf, lsn_t lsn, - bool is_form2); - + bool b_form2); + /*! - Reads nblocks of mode1 sectors from cd device into data starting - from lsn. Returns 0 if no error. - */ + Reads nblocks of mode1 sectors from cd device into data starting + from lsn. Returns 0 if no error. + */ int cdio_read_mode1_sectors (const CdIo *obj, void *buf, lsn_t lsn, - bool is_form2, unsigned int num_sectors); - + bool b_form2, unsigned int num_sectors); + /*! - Reads a single mode2 sector from cd device into data starting - from lsn. Returns 0 if no error. - */ + Reads a single mode2 sector from cd device into data starting + from lsn. Returns 0 if no error. + */ int cdio_read_mode2_sector (const CdIo *obj, void *buf, lsn_t lsn, - bool is_form2); - + bool b_form2); + /*! Reads nblocks of mode2 sectors from cd device into data starting from lsn. Returns 0 if no error. */ int cdio_read_mode2_sectors (const CdIo *obj, void *buf, lsn_t lsn, - bool is_form2, unsigned int num_sectors); + bool b_form2, unsigned int num_sectors); /*! Set the arg "key" with "value" in the source device. @@ -306,49 +314,73 @@ extern "C" { Return the size of the CD in logical block address (LBA) units. */ uint32_t cdio_stat_size (const CdIo *obj); - + /*! Initialize CD Reading and control routines. Should be called first. - */ + */ bool cdio_init(void); - + /* 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. */ + /*! Return a string decribing driver_id. */ const char *cdio_driver_describe (driver_id_t driver_id); /*! 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. */ @@ -360,65 +392,154 @@ 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. + + @see cdio_open + */ 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. + + @see cdio_open_cd + @see cdio_open + */ char * cdio_get_default_device_bsdi(void); + /*! Return a list of all of the CD-ROM devices that the BSDI driver + can find. + */ 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. + + @see cdio_open_cd + @see cdio_open + */ 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. + + @see cdio_open_cd + @see cdio_open + */ 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. + + @see cdio_open_cd + @see cdio_open + */ 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. + + @see cdio_open_cd + @see cdio_open */ 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. + + @see cdio_open_cd + @see cdio_open + */ 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); |