This is fantastic! Thanks. On Sun, Jun 24, 2018 at 8:47 AM, Thomas Schmitt <[email protected]> wrote:
> 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 > > >
