add read_sector{s}

cdtext.h: Small typo.

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 <rocky@panix.com>
     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
+    @see cdio_get_const to retrieve a constant string that doesn't
-    input here.
+    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
+    @see cdio_get to retrieve an allocated string that persists past
-    input here.
+    the cdtext object.
   */
   const char *cdtext_get_const (cdtext_field_t key, const cdtext_t *cdtext);
   

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 <rocky@panix.com>
 
@@ -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 */

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

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 <rocky@panix.com>
 
@@ -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: