[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Libcdio-devel] [RFC] Some clarifications about the API for raw CD-T
From: |
Rocky Bernstein |
Subject: |
Re: [Libcdio-devel] [RFC] Some clarifications about the API for raw CD-TEXT information |
Date: |
Sun, 24 Jun 2018 08:51:31 -0400 |
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
>
>
>