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

[Rocky Bernstein]

This is fantastic! Thanks.

On Sun, Jun 24, 2018 at 8:47 AM, Thomas Schmitt <address@hidden> 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
>
>
>