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
