[Libcdio-devel] [RFC] Some clarifications about the API for raw CD-TEXT information

[Thomas Schmitt]

Hi,

i created my first branch of libcdio's git with the probably too
unspecific name "api-doc".
It is about

  "Some clarifications about the API for raw CD-TEXT information"
  
http://git.savannah.gnu.org/cgit/libcdio.git/commit/?h=api-doc&id=b8f8aff8f6f81c8010d47ed1044188f3db4d680b

Problem with the old text was that it did not explain the raw format
and that some of the statements were obviously made while the functions
were still internal.

I am open to criticism about technical correctness, my language skills,
or clarity.

============================================================================

diff --git a/include/cdio/cdtext.h b/include/cdio/cdtext.h
index afac0e7..2f2b078 100644
--- a/include/cdio/cdtext.h
+++ b/include/cdio/cdtext.h
@@ -253,7 +253,25 @@ const char *cdtext_field2str (cdtext_field_t i);
 cdtext_t *cdtext_init (void);
 
 /*!
-  Read a binary CD-TEXT and fill a cdtext struct.
+  Fill a cdtext_t object with text pack bytes as they were handed out by the
+  CD drive, but without the 4-byte header which the drive prepended.
+
+  The text pack data can be obtained by the calls
+    cdio_get_cdtext_raw()
+    mmc_read_cdtext()
+    mmc_read_toc_cdtext()
+  With each of them, the reply begins by the 4-byte header, which thus needs
+  to be skipped:
+    #include <cdio/mmc_ll_cmds.h>
+    if (DRIVER_OP_SUCCESS == mmc_read_toc_cdtext (p_cdio, &i_length, p_buf, 0)
+        && 4 < i_length)
+        cdtext_data_init(p_cdtext, p_buf + 4, (size_t) i_length - 4);
+
+  An alternative to cdtext_data_init() on a separate cdtext_t object is to call
+    cdio_get_cdtext()
+  which returns a pointer to the cdtext_t object that is attached to the
+  inquired CdIo_t object. This cdtext_t object gets created and filled if
+  none is yet attached to the inquired CdIo_t object.
 
   @param p_cdtext the CD-TEXT object
   @param wdata the data
diff --git a/include/cdio/disc.h b/include/cdio/disc.h
index ef053fd..acd0277 100644
--- a/include/cdio/disc.h
+++ b/include/cdio/disc.h
@@ -58,21 +58,27 @@ extern "C" {
   extern const char *discmode2str[];
 
   /**
-    Get binary CD-Text information for a CdIo_t object.
+    Read cdtext information for a cdtext_t object.
+    About format and usage of these data see the documentation of call
+    mmc_read_cdtext() in include file <cdio/mmc.h>.
 
     @param p_cdio the CD object that may contain CD-Text information.
-    @return malloc'd pointer to raw CD-Text data as stored on the disc or
-    NULL if p_cdio is NULL or CD-Text information does not exist. Return
-    value must be freed with cdio_free() when done with it and not NULL.
+    @return malloc'd pointer to raw CD-Text data as replied by the drive
+            or NULL if problems occur or CD-Text information does not exist.
+            A non-NULL return value must be freed with cdio_free() when done.
   */
   uint8_t * cdio_get_cdtext_raw (CdIo_t *p_cdio);
 
   /** 
-    Get CD-Text information for a CdIo_t object.
+    Return a pointer to the cdtext_t object which is attached to a CdIo_t
+    object. If no such cdtext_t is attached yet, then try to read CD-TEXT
+    information and use it to create and initialise the cdtext_t object.
+
+    For usage of cdtext_t see include file <cdio/cdtext.h>.
  
     @param p_cdio the CD object that may contain CD-Text information.
-    @return the CD-Text object or NULL if p_cdio is NULL
-    or CD-Text information does not exist.
+    @return a pointer to the attached cdtext_t object or NULL if problems
+            occur or if CD-Text information does not exist.
   */
   cdtext_t *cdio_get_cdtext (CdIo_t *p_cdio);
 
diff --git a/include/cdio/mmc.h b/include/cdio/mmc.h
index 2ddc073..5ab249b 100644
--- a/include/cdio/mmc.h
+++ b/include/cdio/mmc.h
@@ -694,10 +694,26 @@ driver_return_code_t mmc_audio_get_volume (CdIo_t 
*p_cdio,  /*out*/
   char * mmc_get_track_isrc(const CdIo_t *p_cdio, track_t i_track);
 
   /**
-    Read cdtext information for a CdIo_t object .
-
-    @return pointer to data on success, NULL on error or CD-Text information 
does
-    not exist.
+    Read cdtext information for a cdtext_t object.
+
+    This is the raw SCSI/MMC reply as retrieved by mmc_read_toc_cdtext().
+    It consists of 4 header bytes and a variable number of text packs.
+    The first two bytes of the header tell as big-endian number the number of
+    bytes to follow. This count includes the next two header bytes which are
+    supposed to bear the value 0.
+    For full detail see include file <cdio/mmc_ll_cmds.h>.
+ 
+    To parse the text packs into a cdtext_t object do:
+      #include <cdio/mmc.h>
+      #include <cdio/cdtext.h>
+
+      reply = mmc_read_cdtext(p_cdio);
+      if (NULL != reply)
+          cdtext_data_init(p_cdtext, reply + 4,
+                           (size_t) CDIO_MMC_GET_LEN16(reply) - 2);
+
+    @return pointer to data on success, NULL on error or if CD-Text
+            information does not exist.
 
     Note: the caller must free the returned memory
 
diff --git a/include/cdio/mmc_ll_cmds.h b/include/cdio/mmc_ll_cmds.h
index a04adb4..e17be57 100644
--- a/include/cdio/mmc_ll_cmds.h
+++ b/include/cdio/mmc_ll_cmds.h
@@ -388,6 +388,26 @@ mmc_read_subchannel ( const CdIo_t *p_cdio,
 /**
    Issue a READ TOC/PMA/ATIP command to read the CD-TEXT from R-W sub-channel.
 
+   In case of success this command returns a header of 4 bytes and the bytes
+   of the text packs. See MMC-5, table 495.
+   The first two bytes of the header tell as big-endian number the number of
+   bytes to follow. This count includes the next two header bytes which are
+   supposed to bear the value 0.
+
+   So the number of bytes in the text packs is told by
+     #include <cdio/mmc.h>
+     CDIO_MMC_GET_LEN16(p_buf) - 2
+   and start of the text packs is at
+     p_buf + 4
+
+   The number of valid reply bytes is further restricted by the submitted
+   value of *i_length, which should tell the byte capacity of p_buf.
+   Maximum size according to specs is 4 + 8 * 256 * 18 = 36864 bytes.
+   Alternatively consider to first obtain only the header bytes in a small
+   p_buf, then to re-allocate p_buf with CDIO_MMC_GET_LEN16(p_buf) + 2 bytes,
+   and then to call mmc_read_toc_cdtext() again with *i_length set to the
+   allocated size.
+
    @param p_cdio  the CD object to be acted upon.
    @param i_length pointer to number of bytes to request.
                    Will be overwritten by the number of bytes available.

============================================================================


Have a nice day :)

Thomas