[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Libcdio-devel] [RFC] Some clarifications about the API for raw CD-TEXT
From: |
Thomas Schmitt |
Subject: |
[Libcdio-devel] [RFC] Some clarifications about the API for raw CD-TEXT information |
Date: |
Sun, 24 Jun 2018 14:47:46 +0200 |
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
- [Libcdio-devel] [RFC] Some clarifications about the API for raw CD-TEXT information,
Thomas Schmitt <=