Add cdio_driver_return_code_to_str() to give a string interpretation

of a driver return code.

include/cdio/device.h

@@ -1,5 +1,5 @@
 /* -*- c -*-
-    $Id: device.h,v 1.29 2006/01/14 10:09:55 rocky Exp $
+    $Id: device.h,v 1.30 2006/01/15 01:26:50 rocky Exp $
 
     Copyright (C) 2005, 2006 Rocky Bernstein <rocky@panix.com>
 
@@ -226,7 +226,8 @@ extern "C" {
   /*!
     Close media tray in CD drive if there is a routine to do so. 
     
-    @param psz_drive the name of CD-ROM to be closed.
+    @param psz_drive the name of CD-ROM to be closed. If NULL, we will
+    use the default device.
     @param p_driver_id is the driver to be used or that got used if
     it was DRIVER_UNKNOWN or DRIVER_DEVICE; If this is NULL, we won't
     report back the driver used.
@@ -234,6 +235,12 @@ extern "C" {
   driver_return_code_t cdio_close_tray (const char *psz_drive, 
 					/*in/out*/ driver_id_t *p_driver_id);
 
+  /*!
+    @param drc the return code you want interpreted.
+    @return the string information about drc
+  */
+  const char *cdio_driver_return_code_to_str(driver_return_code_t drc);
+  
   /*!
     Eject media in CD drive if there is a routine to do so. 
 
@@ -466,20 +473,21 @@ extern "C" {
   
   /*! Sets up to read from place specified by psz_source and
      driver_id. This or cdio_open_* should be called before using any
-     other routine, except cdio_init. This will call cdio_init, if
+     other routine, except cdio_init or any routine that accesses the
-     that hasn't been done previously.  to call one of the specific
+     CD-ROM drive by name. cdio_open will call cdio_init, if that hasn't
-     cdio_open_xxx routines.
+     been done previously.
 
-     @return the cdio object or NULL on error or no device.
+     @return the cdio object or NULL on error or no device.  If NULL
-     If NULL is given as the source, we'll use the default driver device.
+     is given as the source, we'll use the default driver device.
   */
   CdIo_t * cdio_open (const char *psz_source, driver_id_t driver_id);
 
   /*! Sets up to read from place specified by psz_source, driver_id
-     and access mode. This or cdio_open should be called before using
+     and access mode. This or cdio_open* should be called before using
-     any other routine, except cdio_init. This will call cdio_init, if
+     any other routine, except cdio_init or any routine that accesses
-     that hasn't been done previously.  to call one of the specific
+     the CD-ROM drive by name. This will call cdio_init, if that
-     cdio_open_xxx routines.
+     hasn't been done previously.
+
      If NULL is given as the source, we'll use the default driver device.
 
      @return the cdio object or NULL on error or no device.

lib/driver/device.c

@@ -1,5 +1,5 @@
 /*
-    $Id: device.c,v 1.30 2006/01/14 10:10:34 rocky Exp $
+    $Id: device.c,v 1.31 2006/01/15 01:26:50 rocky Exp $
 
     Copyright (C) 2005, 2006 Rocky Bernstein <rocky@panix.com>
 
@@ -242,6 +242,31 @@ CdIo_driver_t CdIo_all_drivers[CDIO_MAX_DRIVER+1] = {
 
 };
 
+const char *
+cdio_driver_return_code_to_str(driver_return_code_t drc)
+{
+  switch(drc) {
+  case DRIVER_OP_SUCCESS: 
+    return "driver operation was successful";
+  case DRIVER_OP_ERROR:
+    return "driver I/O error";
+  case DRIVER_OP_UNSUPPORTED:
+    return "driver operatation not supported";
+  case DRIVER_OP_UNINIT:
+    return "driver not initialized";
+  case DRIVER_OP_NOT_PERMITTED:
+    return "driver operatation not permitted";
+  case DRIVER_OP_BAD_PARAMETER:
+    return "bad parameter passed";
+  case DRIVER_OP_BAD_POINTER:
+    return "bad pointer to memory area";
+  case DRIVER_OP_NO_DRIVER:
+    return "driver not available";
+  default:
+    return "unknown or bad driver return status";
+  }
+}
+
 static CdIo *
 scan_for_driver(driver_id_t start, driver_id_t end, 
                 const char *psz_source, const char *access_mode) 
@@ -313,19 +338,27 @@ cdio_destroy (CdIo_t *p_cdio)
 /*!
   Close media tray in CD drive if there is a routine to do so. 
   
-  @param psz_drive the name of CD-ROM to be closed.
+  @param psz_drive the name of CD-ROM to be closed. If NULL, we will
+  use the default device.
   @param p_driver_id is the driver to be used or that got used if
   it was DRIVER_UNKNOWN or DRIVER_DEVICE; If this is NULL, we won't
   report back the driver used.
 */
 driver_return_code_t 
-cdio_close_tray (const char *psz_drive, /*in/out*/ driver_id_t
+cdio_close_tray (const char *psz_orig_drive, /*in/out*/ driver_id_t
                  *p_driver_id)
 {
   driver_id_t temp_driver_id = DRIVER_DEVICE;
+  char *psz_drive;
+  driver_return_code_t drc;
 
   if (!p_driver_id) p_driver_id = &temp_driver_id;
   
+  if (!psz_orig_drive || !*psz_orig_drive)
+    psz_drive = cdio_get_default_device_driver(p_driver_id);
+  else 
+    psz_drive = strdup(psz_orig_drive);
+  
   if (DRIVER_UNKNOWN == *p_driver_id || DRIVER_DEVICE == *p_driver_id) {
     *p_driver_id = CDIO_MIN_DEVICE_DRIVER;
     
@@ -333,7 +366,9 @@ cdio_close_tray (const char *psz_drive, /*in/out*/ driver_id_t
     for ( ; *p_driver_id<=CDIO_MAX_DRIVER; (*p_driver_id)++) {
       if ( (*CdIo_all_drivers[*p_driver_id].have_driver)() &&
            *CdIo_all_drivers[*p_driver_id].close_tray ) {
-        return (*CdIo_all_drivers[*p_driver_id].close_tray)(psz_drive);
+        drc = (*CdIo_all_drivers[*p_driver_id].close_tray)(psz_drive);
+        free(psz_drive);
+        return drc;
       }
     }
     return DRIVER_OP_UNSUPPORTED;
@@ -342,7 +377,9 @@ cdio_close_tray (const char *psz_drive, /*in/out*/ driver_id_t
   /* The driver id was specified. Use that. */
   if ( (*CdIo_all_drivers[*p_driver_id].have_driver)() &&
        *CdIo_all_drivers[*p_driver_id].close_tray ) {
-    return (*CdIo_all_drivers[*p_driver_id].close_tray)(psz_drive);
+    drc = (*CdIo_all_drivers[*p_driver_id].close_tray)(psz_drive);
+    free(psz_drive);
+    return drc;
   }
   return DRIVER_OP_UNSUPPORTED;
 }
@@ -839,7 +876,7 @@ cdio_open_am (const char *psz_orig_source, driver_id_t driver_id,
   
   if (CdIo_last_driver == -1) cdio_init();
 
-  if (NULL == psz_orig_source || strlen(psz_orig_source)==0) 
+  if (!psz_orig_source || !*psz_orig_source)
     psz_source = cdio_get_default_device(NULL);
   else 
     psz_source = strdup(psz_orig_source);

lib/driver/libcdio.sym

@@ -1,3 +1,4 @@
+CDIO_SECTOR_SYNC_HEADER
 _cdio_list_append
 _cdio_list_begin
 _cdio_list_end
@@ -26,6 +27,7 @@ cdio_close_tray
 cdio_debug
 cdio_destroy
 cdio_driver_describe
+cdio_driver_return_code_to_str
 cdio_eject_media
 cdio_eject_media_drive
 cdio_error
@@ -66,10 +68,10 @@ cdio_get_driver_name
 cdio_get_first_track_num
 cdio_get_hwinfo
 cdio_get_joliet_level
-cdio_get_last_track_num
 cdio_get_last_session
-cdio_get_media_changed
+cdio_get_last_track_num
 cdio_get_mcn
+cdio_get_media_changed
 cdio_get_num_tracks
 cdio_get_track
 cdio_get_track_channels
@@ -175,17 +177,17 @@ discmode2str
 mmc_audio_read_subchannel
 mmc_audio_state2str
 mmc_eject_media
+mmc_feature2str
+mmc_feature_profile2str
 mmc_get_blocksize
+mmc_get_cmd_len
 mmc_get_discmode
 mmc_get_drive_mmc_cap
 mmc_get_dvd_struct_physical
-mmc_get_cmd_len
-mmc_get_media_changed
-mmc_get_mcn
 mmc_get_hwinfo
 mmc_get_last_lsn
-mmc_feature2str
+mmc_get_mcn
-mmc_feature_profile2str
+mmc_get_media_changed
 mmc_have_interface
 mmc_mode_sense
 mmc_mode_sense_10
@@ -200,4 +202,3 @@ mmc_set_speed
 mmc_start_stop_media
 mmc_timeout_ms
 track_format2str
-CDIO_SECTOR_SYNC_HEADER