diff options
author | Mauro Carvalho Chehab <m.chehab@samsung.com> | 2014-09-11 17:28:40 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <m.chehab@samsung.com> | 2014-09-11 17:37:21 -0300 |
commit | bc9ea17ece77ac12b3a4eff0c43f7bf4135e01d4 (patch) | |
tree | 186f26bbc0d9f974208efd858dbf005977dcf1b1 | |
parent | fd2d424f8382868593e4e08cf303585b1c1bbe5b (diff) |
libdvbv5: add documentation for ATSC EIT.
ATSC EIT is different than the DVB EIT table. Document it, and
be sure that the DVB EIT table will be better described.
Signed-off-by: Mauro Carvalho Chehab <m.chehab@samsung.com>
-rw-r--r-- | doxygen_libdvbv5.cfg | 1 | ||||
-rw-r--r-- | lib/include/libdvbv5/atsc_eit.h | 127 | ||||
-rw-r--r-- | lib/include/libdvbv5/eit.h | 23 | ||||
-rw-r--r-- | lib/include/libdvbv5/vct.h | 2 |
4 files changed, 139 insertions, 14 deletions
diff --git a/doxygen_libdvbv5.cfg b/doxygen_libdvbv5.cfg index c717625e..b9481826 100644 --- a/doxygen_libdvbv5.cfg +++ b/doxygen_libdvbv5.cfg @@ -753,6 +753,7 @@ INPUT = $(SRCDIR)/doc/libdvbv5-index.doc \ $(SRCDIR)/lib/include/libdvbv5/dvb-v5-std.h \ $(SRCDIR)/lib/include/libdvbv5/descriptors.h \ $(SRCDIR)/lib/include/libdvbv5/header.h \ + $(SRCDIR)/lib/include/libdvbv5/atsc_eit.h \ $(SRCDIR)/lib/include/libdvbv5/eit.h \ $(SRCDIR)/lib/include/libdvbv5/nit.h \ $(SRCDIR)/lib/include/libdvbv5/pat.h \ diff --git a/lib/include/libdvbv5/atsc_eit.h b/lib/include/libdvbv5/atsc_eit.h index 5116a3d0..7d0b7289 100644 --- a/lib/include/libdvbv5/atsc_eit.h +++ b/lib/include/libdvbv5/atsc_eit.h @@ -18,6 +18,24 @@ * */ +/** + * @file atsc_eit.h + * @brief Provides the table parser for the ATSC EIT (Event Information Table) + * @copyright GNU General Public License version 2 (GPLv2) + * @author Mauro Carvalho Chehab + * @author Andre Roth + * + * @par Relevant specs + * The table described herein is defined at: + * - ATSC A/65:2009 + * + * @see + * http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/eitks.aspx + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org + */ + #ifndef _ATSC_EIT_H #define _ATSC_EIT_H @@ -27,8 +45,39 @@ #include <libdvbv5/atsc_header.h> +/** + * @def ATSC_TABLE_EIT + * @brief ATSC EIT table ID for the actual TS + */ #define ATSC_TABLE_EIT 0xCB +/** + * @struct atsc_table_eit_event + * @brief ATSC EIT event table + * + * @param event_id an uniquelly (inside a service ID) event ID + * @param one Always '1' + * @param title_length title length. Zero means no title + * @param duration duration in seconds + * @param etm Extended Text Message location + * @param one2 Always '1' + * @param descriptor pointer to struct descriptor + * @param next pointer to struct next + * @param source_id source id (obtained from ATSC header) + * @param start event start (in struct tm format) + * + * This structure is used to store the original ATSC EIT event table, + * converting the integer fields to the CPU endianness, and converting the + * timestamps to a way that it is better handled on Linux. + * + * The undocumented parameters are used only internally by the API and/or + * are fields that are reserved. They shouldn't be used, as they may change + * on future API releases. + * + * Everything after atsc_table_eit_event::descriptor (including it) won't + * be bit-mapped to the data parsed from the MPEG TS. So, metadata are added + * there. + */ struct atsc_table_eit_event { union { uint16_t bitfield; @@ -54,6 +103,20 @@ struct atsc_table_eit_event { uint16_t source_id; } __attribute__((packed)); +/** + * @union atsc_table_eit_desc_length + * @brief ATSC EIT descriptor length + * + * @param desc_length descriptor length + * + * This structure is used to store the original ATSC EIT event table, + * converting the integer fields to the CPU endianness, and converting the + * timestamps to a way that it is better handled on Linux. + * + * The undocumented parameters are used only internally by the API and/or + * are fields that are reserved. They shouldn't be used, as they may change + * on future API releases. + */ union atsc_table_eit_desc_length { uint16_t bitfield; struct { @@ -62,12 +125,32 @@ union atsc_table_eit_desc_length { } __attribute__((packed)); } __attribute__((packed)); +/** + * @struct atsc_table_eit + * @brief ATSC EIT table + * + * @param events events + * @param event pointer to struct event + * + * This structure is used to store the original ATSC EIT table, + * converting the integer fields to the CPU endianness. + * + * Everything after atsc_table_eit::event (including it) won't + * be bit-mapped to the data parsed from the MPEG TS. So, metadata are added + * there. + */ struct atsc_table_eit { ATSC_HEADER(); uint8_t events; struct atsc_table_eit_event *event; } __attribute__((packed)); +/** + * @brief Macro used to find event on an ATSC EIT table + * + * @param _event event to seek + * @param _eit pointer to struct atsc_table_eit_event + */ #define atsc_eit_event_foreach(_event, _eit) \ for( struct atsc_table_eit_event *_event = _eit->event; _event; _event = _event->next ) \ @@ -77,9 +160,47 @@ struct dvb_v5_fe_parms; extern "C" { #endif -ssize_t atsc_table_eit_init (struct dvb_v5_fe_parms *parms, const uint8_t *buf, ssize_t buflen, struct atsc_table_eit **table); -void atsc_table_eit_free(struct atsc_table_eit *eit); -void atsc_table_eit_print(struct dvb_v5_fe_parms *parms, struct atsc_table_eit *eit); +/** + * @brief Initializes and parses ATSC EIT table + * + * @param parms struct dvb_v5_fe_parms pointer to the opened device + * @param buf buffer containing the EIT raw data + * @param buflen length of the buffer + * @param table pointer to struct atsc_table_eit to be allocated and filled + * + * This function allocates an ATSC EIT table and fills the fields inside + * the struct. It also makes sure that all fields will follow the CPU + * endianness. Due to that, the content of the buffer may change. + * + * @return On success, it returns the size of the allocated struct. + * A negative value indicates an error. + */ +ssize_t atsc_table_eit_init(struct dvb_v5_fe_parms *parms, const uint8_t *buf, + ssize_t buflen, struct atsc_table_eit **table); + +/** + * @brief Frees all data allocated by the ATSC EIT table parser + * + * @param table pointer to struct atsc_table_eit to be freed + */ +void atsc_table_eit_free(struct atsc_table_eit *table); + +/** + * @brief Prints the content of the ATSC EIT table + * + * @param parms struct dvb_v5_fe_parms pointer to the opened device + * @param table pointe to struct atsc_table_eit + */ +void atsc_table_eit_print(struct dvb_v5_fe_parms *parms, + struct atsc_table_eit *table); + +/** + * @brief Converts an ATSC EIT formatted timestamp into struct tm + * + * @param start_time event on ATSC EIT time format + * @param tm pointer to struct tm where the converted timestamp will + * be stored. + */ void atsc_time(const uint32_t start_time, struct tm *tm); #ifdef __cplusplus diff --git a/lib/include/libdvbv5/eit.h b/lib/include/libdvbv5/eit.h index 8f824e73..16e978ea 100644 --- a/lib/include/libdvbv5/eit.h +++ b/lib/include/libdvbv5/eit.h @@ -21,7 +21,7 @@ /** * @file eit.h - * @brief Provides the table parser for EIT (Event Information Table) + * @brief Provides the table parser for the DVB EIT (Event Information Table) * @copyright GNU General Public License version 2 (GPLv2) * @author Mauro Carvalho Chehab * @author Andre Roth @@ -30,6 +30,9 @@ * The table described herein is defined at: * - ETSI EN 300 468 * + * @see + * http://www.etherguidesystems.com/Help/SDOs/dvb/syntax/tablesections/EIT.aspx + * * @par Bug Report * Please submit bug reports and patches to linux-media@vger.kernel.org */ @@ -45,15 +48,15 @@ /** * @def DVB_TABLE_EIT - * @brief EIT table ID for the actual TS + * @brief DVB EIT table ID for the actual TS * @def DVB_TABLE_EIT_OTHER - * @brief EIT table ID for other TS + * @brief DVB EIT table ID for other TS * @def DVB_TABLE_EIT_PID - * @brief EIT Program ID + * @brief DVB EIT Program ID * @def DVB_TABLE_EIT_SCHEDULE - * @brief Start table ID for the EIT schedule data on the actual TS + * @brief Start table ID for the DVB EIT schedule data on the actual TS * @def DVB_TABLE_EIT_SCHEDULE_OTHER - * @brief Start table ID for the EIT schedule data on other TS + * @brief Start table ID for the DVB EIT schedule data on other TS */ #define DVB_TABLE_EIT 0x4E #define DVB_TABLE_EIT_OTHER 0x4F @@ -140,7 +143,7 @@ struct dvb_table_eit { } __attribute__((packed)); /** - * @brief Macro used to find event on a EIT table + * @brief Macro used to find event on a DVB EIT table * * @param _event event to seek * @param _eit pointer to struct dvb_table_eit_event @@ -163,7 +166,7 @@ extern "C" { * @param parms struct dvb_v5_fe_parms pointer to the opened device * @param buf buffer containing the EIT raw data * @param buflen length of the buffer - * @param table pointer to struct dvb_table_pat to be allocated and filled + * @param table pointer to struct dvb_table_eit to be allocated and filled * * This function allocates an EIT table and fills the fields inside * the struct. It also makes sure that all fields will follow the CPU @@ -176,14 +179,14 @@ ssize_t dvb_table_eit_init (struct dvb_v5_fe_parms *parms, const uint8_t *buf, ssize_t buflen, struct dvb_table_eit **table); /** - * @brief Frees all data allocated by the EIT table parser + * @brief Frees all data allocated by the DVB EIT table parser * * @param table pointer to struct dvb_table_eit to be freed */ void dvb_table_eit_free(struct dvb_table_eit *table); /** - * @brief Prints the content of the EIT table + * @brief Prints the content of the DVB EIT table * * @param parms struct dvb_v5_fe_parms pointer to the opened device * @param table pointe to struct dvb_table_eit diff --git a/lib/include/libdvbv5/vct.h b/lib/include/libdvbv5/vct.h index 9b69aa0e..4b9e03b6 100644 --- a/lib/include/libdvbv5/vct.h +++ b/lib/include/libdvbv5/vct.h @@ -28,7 +28,7 @@ * * @par Relevant specs * The table described herein is defined at: - * - ATSC A/65:2009 spec + * - ATSC A/65:2009 * * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/TVCT.aspx * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/CVCT.aspx |