diff --git a/include/cdio/cdtext.h b/include/cdio/cdtext.h index 66369261..fbf49ebd 100644 --- a/include/cdio/cdtext.h +++ b/include/cdio/cdtext.h @@ -1,5 +1,5 @@ /* - $Id: cdtext.h,v 1.11 2005/04/25 23:06:21 rocky Exp $ + $Id: cdtext.h,v 1.12 2005/11/10 00:44:40 rocky Exp $ Copyright (C) 2004, 2005 Rocky Bernstein adapted from cuetools @@ -81,8 +81,8 @@ extern "C" { The user needs to free the string when done with it. - @see cdio_get_cdtext to retrieve the cdtext structure used as - input here. + @see cdio_get_const to retrieve a constant string that doesn't + have to be freed. */ char *cdtext_get (cdtext_field_t key, const cdtext_t *cdtext); @@ -92,8 +92,8 @@ extern "C" { Don't use the string when the cdtext object (i.e. the CdIo_t object you got it from) is no longer valid. - @see cdio_get_cdtext to retrieve the cdtext structure used as - input here. + @see cdio_get to retrieve an allocated string that persists past + the cdtext object. */ const char *cdtext_get_const (cdtext_field_t key, const cdtext_t *cdtext); diff --git a/include/cdio/read.h b/include/cdio/read.h index 1aae1351..e9fe9829 100644 --- a/include/cdio/read.h +++ b/include/cdio/read.h @@ -1,5 +1,5 @@ /* -*- c -*- - $Id: read.h,v 1.6 2005/03/21 09:19:06 rocky Exp $ + $Id: read.h,v 1.7 2005/11/10 00:44:40 rocky Exp $ Copyright (C) 2005 Rocky Bernstein @@ -31,6 +31,15 @@ extern "C" { #endif /* __cplusplus */ + /** All the different ways a block/sector can be read. */ + typedef enum { + CDIO_READ_MODE_AUDIO, /**< CD-DA, audio, Red Book */ + CDIO_READ_MODE_M1F1, /**< Mode 1 Form 1 */ + CDIO_READ_MODE_M1F2, /**< Mode 1 Form 2 */ + CDIO_READ_MODE_M2F1, /**< Mode 2 Form 1 */ + CDIO_READ_MODE_M2F2, /**< Mode 2 Form 2 */ + } cdio_read_mode_t; + /*! Reposition read offset Similar to (if not the same as) libc's lseek() @@ -84,7 +93,7 @@ extern "C" { uint32_t i_blocks); /*! - Read a data sector + Read data sectors @param p_cdio object to read from @param p_buf place to read data into. The caller should make sure @@ -104,7 +113,6 @@ extern "C" { void *p_buf, lsn_t i_lsn, uint16_t i_blocksize, uint32_t i_blocks ); - /*! Reads a mode 1 sector @@ -117,7 +125,6 @@ extern "C" { driver_return_code_t cdio_read_mode1_sector (const CdIo_t *p_cdio, void *p_buf, lsn_t i_lsn, bool b_form2); - /*! Reads mode 1 sectors @@ -132,7 +139,6 @@ extern "C" { void *p_buf, lsn_t i_lsn, bool b_form2, uint32_t i_blocks); - /*! Reads a mode 2 sector @@ -151,6 +157,12 @@ extern "C" { void *p_buf, lsn_t i_lsn, bool b_form2); + /** The special case of reading a single block is a common one so we + provide a routine for that as a convenience. + */ + driver_return_code_t cdio_read_sector(const CdIo_t *p_cdio, void *p_buf, + lsn_t i_lsn, + cdio_read_mode_t read_mode); /*! Reads mode 2 sectors @@ -171,6 +183,39 @@ extern "C" { bool b_form2, uint32_t i_blocks); + /*! + Reads a number of sectors (AKA blocks). + + @param p_buf place to read data into. The caller should make sure + this location is large enough. See below for size information. + @param read_mode the kind of "mode" to use in reading. + @param i_lsn sector to read + @param i_blocks number of sectors to read + @return DRIVER_OP_SUCCESS (0) if no error, other (negative) enumerations + are returned on error. + + If read_mode is CDIO_MODE_AUDIO, + *p_buf should hold at least CDIO_FRAMESIZE_RAW * i_blocks bytes. + + If read_mode is CDIO_MODE_DATA, + *p_buf should hold at least i_blocks times either ISO_BLOCKSIZE, + M1RAW_SECTOR_SIZE or M2F2_SECTOR_SIZE depending on the kind of + sector getting read. If you don't know whether you have a Mode 1/2, + Form 1/ Form 2/Formless sector best to reserve space for the maximum + which is M2RAW_SECTOR_SIZE. + + If read_mode is CDIO_MODE_M2F1, + *p_buf should hold at least M2RAW_SECTOR_SIZE * i_blocks bytes. + + If read_mode is CDIO_MODE_M2F2, + *p_buf should hold at least CDIO_CD_FRAMESIZE * i_blocks bytes. + + */ + driver_return_code_t cdio_read_sectors(const CdIo_t *p_cdio, void *p_buf, + lsn_t i_lsn, + cdio_read_mode_t read_mode, + uint32_t i_blocks); + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/lib/driver/libcdio.sym b/lib/driver/libcdio.sym index b3d5ba40..40c11506 100644 --- a/lib/driver/libcdio.sym +++ b/lib/driver/libcdio.sym @@ -147,6 +147,8 @@ cdio_read_mode1_sector cdio_read_mode1_sectors cdio_read_mode2_sector cdio_read_mode2_sectors +cdio_read_sector +cdio_read_sectors cdio_set_arg cdio_set_blocksize cdio_set_speed diff --git a/lib/driver/read.c b/lib/driver/read.c index 9d6ecd95..6c583cee 100644 --- a/lib/driver/read.c +++ b/lib/driver/read.c @@ -1,5 +1,5 @@ /* - $Id: read.c,v 1.9 2005/10/07 07:15:19 rocky Exp $ + $Id: read.c,v 1.10 2005/11/10 00:44:41 rocky Exp $ Copyright (C) 2005 Rocky Bernstein @@ -254,6 +254,65 @@ cdio_read_mode2_sectors (const CdIo_t *p_cdio, void *p_buf, lsn_t i_lsn, } + +/** The special case of reading a single block is a common one so we + provide a routine for that as a convenience. +*/ +driver_return_code_t +cdio_read_sector(const CdIo_t *p_cdio, void *p_buf, lsn_t i_lsn, + cdio_read_mode_t read_mode) +{ + return cdio_read_sectors(p_cdio, p_buf, i_lsn, read_mode, 1); +} + +/*! + Reads a number of sectors (AKA blocks). + + @param p_buf place to read data into. The caller should make sure + this location is large enough. See below for size information. + @param read_mode the kind of "mode" to use in reading. + @param i_lsn sector to read + @param i_blocks number of sectors to read + @return DRIVER_OP_SUCCESS (0) if no error, other (negative) enumerations + are returned on error. + + If read_mode is CDIO_MODE_AUDIO, + *p_buf should hold at least CDIO_FRAMESIZE_RAW * i_blocks bytes. + + If read_mode is CDIO_MODE_DATA, + *p_buf should hold at least i_blocks times either ISO_BLOCKSIZE, + M1RAW_SECTOR_SIZE or M2F2_SECTOR_SIZE depending on the kind of + sector getting read. If you don't know whether you have a Mode 1/2, + Form 1/ Form 2/Formless sector best to reserve space for the maximum + which is M2RAW_SECTOR_SIZE. + + If read_mode is CDIO_MODE_M2F1, + *p_buf should hold at least M2RAW_SECTOR_SIZE * i_blocks bytes. + + If read_mode is CDIO_MODE_M2F2, + *p_buf should hold at least CDIO_CD_FRAMESIZE * i_blocks bytes. + + +*/ +driver_return_code_t +cdio_read_sectors(const CdIo_t *p_cdio, void *p_buf, lsn_t i_lsn, + cdio_read_mode_t read_mode, uint32_t i_blocks) +{ + switch(read_mode) { + case CDIO_READ_MODE_AUDIO: + return cdio_read_audio_sectors (p_cdio, p_buf, i_lsn, i_blocks); + case CDIO_READ_MODE_M1F1: + return cdio_read_mode1_sectors (p_cdio, p_buf, i_lsn, false, i_blocks); + case CDIO_READ_MODE_M1F2: + return cdio_read_mode1_sectors (p_cdio, p_buf, i_lsn, true, i_blocks); + case CDIO_READ_MODE_M2F1: + return cdio_read_mode2_sectors (p_cdio, p_buf, i_lsn, false, i_blocks); + case CDIO_READ_MODE_M2F2: + return cdio_read_mode2_sectors (p_cdio, p_buf, i_lsn, true, i_blocks); + } + /* Can't happen. Just to shut up gcc. */ + return DRIVER_OP_ERROR; +} /* * Local variables: