More powerfull API documentation.

Added Some human readable documentation
Added a .cvsignore

doc/decoder.dot

+digraph decoder {
+  "app" [ label="Application"
+          color="blue4" ];
+  "psi_dec" [ label="PSI decoder"
+              color="red3" ];
+  "specific_dec" [ label="Specific decoder"
+                   color="green4" ];
+
+  app -> psi_dec -> specific_dec -> app
+}

doc/doxygen.cfg

@@ -47,7 +47,7 @@ OUTPUT_LANGUAGE        = English
 # Private class members and static file members will be hidden unless 
 # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
 
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
 
 # If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
 # will be included in the documentation.
@@ -139,7 +139,7 @@ STRIP_CODE_COMMENTS    = YES
 # in case and if your file system supports case sensitive file names. Windows 
 # users are adviced to set this option to NO.
 
-CASE_SENSE_NAMES       = YES
+CASE_SENSE_NAMES       = NO
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
 # (but less readable) file names. This can be useful is your file systems 
@@ -163,7 +163,7 @@ VERBATIM_HEADERS       = YES
 # will put list of the files that are included by a file in the documentation 
 # of that file.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen 
 # will interpret the first line (until the first dot) of a JavaDoc-style 
@@ -301,7 +301,11 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../src ../src/tables
+INPUT                  = index.doxygen \
+                         structure.doxygen \
+                         usage.doxygen \
+                         newdec.doxygen \
+                         ../src ../src/tables
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -846,7 +850,7 @@ DOT_PATH               =
 # contain dot files that are included in the documentation (see the 
 # \dotfile command).
 
-DOTFILE_DIRS           = 
+DOTFILE_DIRS           = .
 
 # The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width 
 # (in pixels) of the graphs generated by dot. If a graph becomes larger than 

doc/index.doxygen

+/*! \page Index libdvbpsi's documentation
+
+\author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+
+<h2>Preface</h2>
+
+<p>The <em>libdvbpsi</em> is a library developed by the <a
+href="http://www.videolan.org/">VideoLAN</a> team. This document
+describes how to use it and the "C" API.</p>
+
+<h2>What is libdvbpsi ?</h2>
+
+<p><em>libdvbpsi</em> is a set of tools which allows to decode and generate all the Program specific Information (<em>PSI</em>) present in a MPEG2 TS or a DVB stream. The two keywords are <em>portability</em> and <em>simplicity</em></p>
+
+<h2>Currently supported tables</h2>
+
+<ul>
+  <li>Program Association Table (<em>PAT</em>, MPEG2)</li>
+  <li>Program Map Table (<em>PMT</em>, MPEG2)</li>
+</ul>
+
+<h2>Usage</h2>
+
+<ul>
+  <li>\ref structure</li>
+  <li>\ref usage</li>
+  <li>\ref newdec</li>
+</ul>
+
+*/

doc/newdec.doxygen

+/*! \page newdec How to implement a new specific decoder ?
+
+<p>Look at the PAT example. Especially how the PSI decoder is
+initialized. It's mandatory to check the
+dvbpsi_decoder_s::b_discontinuity flag each time the PSI decoder calls
+the specific decoder and then to reset it to 0.</p>
+
+*/

doc/structure.doxygen

+/*! \page structure Structure of the decoders
+
+<p>The PSI decoder and the specific decoder:</p>
+
+\dotfile decoder.dot "Decoder entities"
+
+<p>Each decoder is split into two entities:</p>
+
+<ul>
+  <li>the <em>PSI decoder</em></li>
+  <li>the <em>specific decoder</em></li>
+</ul>
+
+<p>The reason of this split is that each PSI section has a common
+format. The main task of the <em>PSI decoder</em> is to get the TS
+packets given by the <em>application</em> and send complete PSI sections
+to the <em>specific decoder</em>. The <em>PSI decoder</em> must be
+reliable on TS discontinuities and signal them to the <em>specific
+decoder</em>.</p>
+
+<p>The task of the <em>specific decoder</em> is to get the PSI sections
+given by the <em>PSI decoder</em>, to build complete tables and to send
+them back to the <em>application</em>. At the same time it has to check
+TS discontinuities signaled by the <em>PSI decoder</em>. </p>
+
+<p>The <em>PSI decoder</em> is common to all the decoders wheras the
+<em>specific decoder</em> must be implemented for all the PSI
+tables.</p>
+
+\ref usage
+
+*/

doc/usage.doxygen

+/*! \page usage API usage
+
+<p>When the application needs a new decoder it just has to call the
+<em>dvbpsi_AttachXXX()</em> function where XXX is the name of the table
+(ex: dvbpsi_AttachPAT()). The function returns a handle on the new
+decoder.</p>
+
+<p>Then the application has to send the TS packets needed by the decoder
+by calling the dvbpsi_PushPacket() function. If a new table is complete
+then the decoder calls the callback specified by the application when it
+called <em>dvbpsi_AttachXXX()</em>.</p>
+
+<p>When the application don't need the decoder anymore it just has to
+call the <em>dvbpsi_DetachXXX()</em> function (ex:
+dvbpsi_DetachPAT()).</p>
+
+<p>Be careful! If a table wasn't active (b_current_next == 0) and the
+next is the same but active (b_current_next == 1) then the lists
+contained by the table structure are empty and should be caught from the
+previous structure.</p>
+
+<p>In this version of <em>libdvbpsi</em> the descriptors aren't decoded.
+These decoders will come in the next release.</p>
+
+<p>For specific tools, the best to do is to have a look at the include
+file:</p>
+
+<ul>
+  <li>Program Specific Information: psi.h</li>
+  <li>Descriptors: descriptor.h</li>
+  <li>Program Association Table: pat.h</li>
+  <li>Program Map Table: pmt.h</li>
+</ul>
+
+\ref structure
+
+*/

src/descriptor.h

 /*****************************************************************************
- * descriptor.h: common descriptor structures
- *----------------------------------------------------------------------------
+ * descriptor.h
  * (c)2001-2002 VideoLAN
- * $Id: descriptor.h,v 1.3 2002/03/25 21:00:50 bozo Exp $
+ * $Id: descriptor.h,v 1.4 2002/03/27 20:02:43 bozo Exp $
  *
  * Authors: Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
  *
@@ -20,10 +19,16 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  *
- *----------------------------------------------------------------------------
- *
  *****************************************************************************/
 
+/*!
+ * \file <descriptor.h>
+ * \author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+ * \brief Common descriptor tools.
+ *
+ * Descriptor structure and its Manipulation tools.
+ */
+
 #ifndef _DVBPSI_DESCRIPTOR_H_
 #define _DVBPSI_DESCRIPTOR_H_
 
@@ -35,9 +40,17 @@ extern "C" {
 /*****************************************************************************
  * dvbpsi_descriptor_t
  *****************************************************************************/
-/*!This structure is used to store a descriptor.
+/*!
+ * \struct dvbpsi_descriptor_s
+ * \brief Descriptor structure.
+ *
+ * This structure is used to store a descriptor.
  * (ISO/IEC 13818-1 section 2.6).
- *****************************************************************************/
+ */
+/*!
+ * \typedef struct dvbpsi_descriptor_s dvbpsi_descriptor_t
+ * \brief dvbpsi_descriptor_t type definition.
+ */
 typedef struct dvbpsi_descriptor_s
 {
   uint8_t                       i_tag;          /*!< descriptor_tag */
@@ -54,12 +67,16 @@ typedef struct dvbpsi_descriptor_s
 /*****************************************************************************
  * dvbpsi_NewDescriptor
  *****************************************************************************/
-/*!Creation of a new dvbpsi_descriptor_t structure.
+/*!
+ * \fn dvbpsi_descriptor_t* dvbpsi_NewDescriptor(uint8_t i_tag,
+                                                 uint8_t i_length,
+                                                 uint8_t* p_data)
+ * \brief Creation of a new dvbpsi_descriptor_t structure.
  * \param i_tag descriptor's tag
  * \param i_length descriptor's length
  * \param p_data descriptor's data
  * \return a pointer to the descriptor.
- *****************************************************************************/
+ */
 dvbpsi_descriptor_t* dvbpsi_NewDescriptor(uint8_t i_tag, uint8_t i_length,
                                           uint8_t* p_data);
 
@@ -67,10 +84,12 @@ dvbpsi_descriptor_t* dvbpsi_NewDescriptor(uint8_t i_tag, uint8_t i_length,
 /*****************************************************************************
  * dvbpsi_DeleteDescriptor
  *****************************************************************************/
-/*!Destruction of a dvbpsi_descriptor_t structure.
+/*!
+ * \fn void dvbpsi_DeleteDescriptor(dvbpsi_descriptor_t* p_descriptor)
+ * \brief Destruction of a dvbpsi_descriptor_t structure.
  * \param p_descriptor pointer to the descriptor
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_DeleteDescriptor(dvbpsi_descriptor_t* p_descriptor);
 
 

src/dvbpsi.h

 /*****************************************************************************
- * dvbpsi.h: main header
- *----------------------------------------------------------------------------
+ * dvbpsi.h
  * (c)2001-2002 VideoLAN
- * $Id: dvbpsi.h,v 1.4 2002/03/25 21:00:50 bozo Exp $
+ * $Id: dvbpsi.h,v 1.5 2002/03/27 20:02:43 bozo Exp $
  *
  * Authors: Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
  *
@@ -20,10 +19,17 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  *
- *----------------------------------------------------------------------------
- *
  *****************************************************************************/
 
+/*!
+ * \file <dvbpsi.h>
+ * \author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+ * \brief Application interface for all DVB/PSI decoders.
+ *
+ * Application interface for all DVB/PSI decoders. The generic decoder
+ * structure is public so that external decoders are allowed.
+ */
+
 #ifndef _DVBPSI_DVBPSI_H_
 #define _DVBPSI_DVBPSI_H_
 
@@ -38,19 +44,25 @@ extern "C" {
 /*****************************************************************************
  * dvbpsi_handle
  *****************************************************************************/
-/*!Decoder abstration.
- *****************************************************************************/
+/*!
+ * \typedef struct dvbpsi_decoder_s * dvbpsi_handle
+ * \brief Decoder abstration.
+ */
 typedef struct dvbpsi_decoder_s * dvbpsi_handle;
 
 
 /*****************************************************************************
  * dvbpsi_PushPacket
  *****************************************************************************/
-/*!Injection of a TS packet into a PSI decoder.
+/*!
+ * \fn void dvbpsi_PushPacket(dvbpsi_handle h_dvbpsi, uint8_t* p_data)
+ * \brief Injection of a TS packet into a PSI decoder.
  * \param h_dvbpsi handle to the decoder
  * \param p_data pointer to a 188 bytes playload of a TS packet
  * \return nothing.
- *****************************************************************************/
+ *
+ * Injection of a TS packet into a PSI decoder.
+ */
 void dvbpsi_PushPacket(dvbpsi_handle h_dvbpsi, uint8_t* p_data);
 
 
@@ -59,13 +71,21 @@ void dvbpsi_PushPacket(dvbpsi_handle h_dvbpsi, uint8_t* p_data);
  * shouldn't be used for any other purpose.
  *****************************************************************************/
 
+/*!
+ * \typedef struct dvbpsi_psi_section_s dvbpsi_psi_section_t
+ * \brief dvbpsi_psi_section_t type definition.
+ */
 typedef struct dvbpsi_psi_section_s dvbpsi_psi_section_t;
 
+
 /*****************************************************************************
  * dvbpsi_callback
  *****************************************************************************/
-/*!Callback type definition.
- *****************************************************************************/
+/*!
+ * \typedef void (* dvbpsi_callback)(dvbpsi_handle p_decoder,
+                                     dvbpsi_psi_section_t* p_section)
+ * \brief Callback type definition.
+ */
 typedef void (* dvbpsi_callback)(dvbpsi_handle p_decoder,
                                  dvbpsi_psi_section_t* p_section);
 
@@ -73,22 +93,38 @@ typedef void (* dvbpsi_callback)(dvbpsi_handle p_decoder,
 /*****************************************************************************
  * dvbpsi_decoder_t
  *****************************************************************************/
-/*!PSI decoder.
- *****************************************************************************/
+/*!
+ * \struct dvbpsi_decoder_s
+ * \brief PSI decoder structure.
+ *
+ * This structure shouldn't be used but if you want to write an external
+ * decoder.
+ */
+/*!
+ * \typedef struct dvbpsi_decoder_s dvbpsi_decoder_t
+ * \brief dvbpsi_decoder_t type definition.
+ */
 typedef struct dvbpsi_decoder_s
 {
-  dvbpsi_callback               pf_callback;
+  dvbpsi_callback               pf_callback;            /*!< PSI decoder's
+                                                             callback */
 
-  void *                        p_private_decoder;
+  void *                        p_private_decoder;      /*!< specific
+                                                             decoder */
 
-  int                           i_section_max_size;
+  int                           i_section_max_size;     /*!< Max size of a
+                                                             section for this
+                                                             decoder */
 
-  uint8_t                       i_continuity_counter;
-  int                           b_discontinuity;
+  uint8_t                       i_continuity_counter;   /*!< Continuity
+                                                             counter */
+  int                           b_discontinuity;        /*!< Discontinuity
+                                                             flag */
 
-  dvbpsi_psi_section_t *        p_current_section;
-  int                           i_need;
-  int                           b_complete_header;
+  dvbpsi_psi_section_t *        p_current_section;      /*!< Current section */
+  int                           i_need;                 /*!< Bytes needed */
+  int                           b_complete_header;      /*!< Flag for header
+                                                             completion */
 
 } dvbpsi_decoder_t;
 

src/psi.h

 /*****************************************************************************
- * psi.h: common PSI structures
- *----------------------------------------------------------------------------
+ * psi.h
  * (c)2001-2002 VideoLAN
- * $Id: psi.h,v 1.4 2002/03/25 21:00:50 bozo Exp $
+ * $Id: psi.h,v 1.5 2002/03/27 20:02:43 bozo Exp $
  *
  * Authors: Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
  *
@@ -20,10 +19,16 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  *
- *----------------------------------------------------------------------------
- *
  *****************************************************************************/
 
+/*!
+ * \file <psi.h>
+ * \author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+ * \brief Common PSI tools.
+ *
+ * PSI section structure and its Manipulation tools.
+ */
+
 #ifndef _DVBPSI_PSI_H_
 #define _DVBPSI_PSI_H_
 
@@ -35,9 +40,32 @@ extern "C" {
 /*****************************************************************************
  * dvbpsi_psi_section_t
  *****************************************************************************/
-/*!This structure is used to store a PSI section. The common information are
+/*!
+ * \struct dvbpsi_psi_section_s
+ * \brief PSI section structure.
+ *
+ * This structure is used to store a PSI section. The common information are
  * decoded (ISO/IEC 13818-1 section 2.4.4.10).
- *****************************************************************************/
+ *
+ * dvbpsi_psi_section_s::p_data stores the complete section including the
+ * header.
+ *
+ * When dvbpsi_psi_section_s::b_syntax_indicator == 0,
+ * dvbpsi_psi_section_s::p_payload_start points immediately after the
+ * section_length field and dvbpsi_psi_section_s::p_payload_end points
+ * immediately after the end of the section (don't try to access this byte).
+ *
+ * When dvbpsi_psi_section_s::b_syntax_indicator != 0,
+ * dvbpsi_psi_section_s::p_payload_start points immediately after the
+ * last_section_number field and dvbpsi_psi_section_s::p_payload_end points to
+ * the first byte of the CRC_32 field.
+ *
+ * When dvbpsi_psi_section_s::b_syntax_indicator == 0
+ * dvbpsi_psi_section_s::i_extension, dvbpsi_psi_section_s::i_version,
+ * dvbpsi_psi_section_s::b_current_next, dvbpsi_psi_section_s::i_number,
+ * dvbpsi_psi_section_s::i_last_number, and dvbpsi_psi_section_s::i_crc are
+ * undifined.
+ */
 struct dvbpsi_psi_section_s
 {
   /* non-specific section data */
@@ -74,40 +102,50 @@ struct dvbpsi_psi_section_s
 /*****************************************************************************
  * dvbpsi_NewPSISection
  *****************************************************************************/
-/*!Creation of a new dvbpsi_psi_section_t structure.
+/*!
+ * \fn dvbpsi_psi_section_t * dvbpsi_NewPSISection(int i_max_size)
+ * \brief Creation of a new dvbpsi_psi_section_t structure.
  * \param i_max_size max size in bytes of the section
  * \return a pointer to the new PSI section structure.
- *****************************************************************************/
+ */
 dvbpsi_psi_section_t * dvbpsi_NewPSISection(int i_max_size);
 
 
 /*****************************************************************************
  * dvbpsi_DeletePSISections
  *****************************************************************************/
-/*!Destruction of a dvbpsi_psi_section_t structure.
+/*!
+ * \fn void dvbpsi_DeletePSISections(dvbpsi_psi_section_t * p_section)
+ * \brief Destruction of a dvbpsi_psi_section_t structure.
  * \param p_section pointer to the first PSI section structure
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_DeletePSISections(dvbpsi_psi_section_t * p_section);
 
 
 /*****************************************************************************
  * dvbpsi_ValidPSISection
  *****************************************************************************/
-/*!Check the CRC_32 if the section has b_syntax_indicator set.
+/*!
+ * \fn int dvbpsi_ValidPSISection(dvbpsi_psi_section_t* p_section)
+ * \brief Validity check of a PSI section.
  * \param p_section pointer to the PSI section structure
  * \return boolean value (0 if the section is not valid).
- *****************************************************************************/
+ *
+ * Check the CRC_32 if the section has b_syntax_indicator set.
+ */
 int dvbpsi_ValidPSISection(dvbpsi_psi_section_t* p_section);
 
 
 /*****************************************************************************
  * dvbpsi_BuildPSISection
  *****************************************************************************/
-/*!Build the section based on the information in the structure.
+/*!
+ * \fn void dvbpsi_BuildPSISection(dvbpsi_psi_section_t* p_section)
+ * \brief Build a valid section based on the information in the structure.
  * \param p_section pointer to the PSI section structure
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_BuildPSISection(dvbpsi_psi_section_t* p_section);
 
 

src/tables/.cvsignore

+.deps
+.libs
+Makefile
+*.lo
+*.la

src/tables/pat.h

 /*****************************************************************************
- * pat.h: PAT structures
- *----------------------------------------------------------------------------
+ * pat.h
  * (c)2001-2002 VideoLAN
- * $Id: pat.h,v 1.3 2002/03/25 21:00:50 bozo Exp $
+ * $Id: pat.h,v 1.4 2002/03/27 20:02:43 bozo Exp $
  *
  * Authors: Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
  *
@@ -20,10 +19,20 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  *
- *----------------------------------------------------------------------------
- *
  *****************************************************************************/
 
+/*!
+ * \file <pat.h>
+ * \author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+ * \brief Application interface for the PAT decoder and the PAT generator.
+ *
+ * Application interface for the PAT decoder decoder and the PAT generator.
+ * New decoded PAT tables are sent by callback to the application. If a table
+ * wasn't active (b_current_next == 0) and the next is the same but active
+ * (b_current_next == 1) then the program list is empty and should be
+ * caught from the previous structure.
+ */
+
 #ifndef _DVBPSI_PAT_H_
 #define _DVBPSI_PAT_H_
 
@@ -35,9 +44,17 @@ extern "C" {
 /*****************************************************************************
  * dvbpsi_pat_program_t
  *****************************************************************************/
-/*!This structure is used to store a decoded PAT program.
+/*!
+ * \struct dvbpsi_pat_program_s
+ * \brief PAT program structure.
+ *
+ * This structure is used to store a decoded PAT program.
  * (ISO/IEC 13818-1 section 2.4.4.3).
- *****************************************************************************/
+ */
+/*!
+ * \typedef struct dvbpsi_pat_program_s dvbpsi_pat_program_t
+ * \brief dvbpsi_pat_program_t type definition.
+ */
 typedef struct dvbpsi_pat_program_s
 {
   uint16_t                      i_number;               /*!< program_number */
@@ -52,9 +69,17 @@ typedef struct dvbpsi_pat_program_s
 /*****************************************************************************
  * dvbpsi_pat_t
  *****************************************************************************/
-/*!This structure is used to store a decoded PAT.
+/*!
+ * \struct dvbpsi_pat_s
+ * \brief PAT structure.
+ *
+ * This structure is used to store a decoded PAT.
  * (ISO/IEC 13818-1 section 2.4.4.3).
- *****************************************************************************/
+ */
+/*!
+ * \typedef struct dvbpsi_pat_s dvbpsi_pat_t
+ * \brief dvbpsi_pat_t type definition.
+ */
 typedef struct dvbpsi_pat_s
 {
   uint16_t                  i_ts_id;            /*!< transport_stream_id */
@@ -69,19 +94,25 @@ typedef struct dvbpsi_pat_s
 /*****************************************************************************
  * dvbpsi_pat_callback
  *****************************************************************************/
-/*!Callback type definition.
- *****************************************************************************/
+/*!
+ * \typedef void (* dvbpsi_pat_callback)(void* p_cb_data,
+                                         dvbpsi_pat_t* p_new_pat)
+ * \brief Callback type definition.
+ */
 typedef void (* dvbpsi_pat_callback)(void* p_cb_data, dvbpsi_pat_t* p_new_pat);
 
 
 /*****************************************************************************
  * dvbpsi_AttachPAT
  *****************************************************************************/
-/*!Initialize a PAT decoder and return a handle on it.
+/*!
+ * \fn dvbpsi_handle dvbpsi_AttachPAT(dvbpsi_pat_callback pf_callback,
+                                      void* p_cb_data)
+ * \brief Creation and initialization of a PAT decoder.
  * \param pf_callback function to call back on new PAT
  * \param p_cb_data private data given in argument to the callback
  * \return a pointer to the decoder for future calls.
- *****************************************************************************/
+ */
 dvbpsi_handle dvbpsi_AttachPAT(dvbpsi_pat_callback pf_callback,
                                void* p_cb_data);
 
@@ -89,33 +120,42 @@ dvbpsi_handle dvbpsi_AttachPAT(dvbpsi_pat_callback pf_callback,
 /*****************************************************************************
  * dvbpsi_DetachPAT
  *****************************************************************************/
-/*!Close a PAT decoder. The handle isn't valid any more.
+/*!
+ * \fn void dvbpsi_DetachPAT(dvbpsi_handle h_dvbpsi)
+ * \brief Destroy a PAT decoder.
  * \param h_dvbpsi handle to the decoder
  * \return nothing.
- *****************************************************************************/
+ *
+ * The handle isn't valid any more.
+ */
 void dvbpsi_DetachPAT(dvbpsi_handle h_dvbpsi);
 
 
 /*****************************************************************************
  * dvbpsi_InitPAT/dvbpsi_NewPAT
  *****************************************************************************/
-/*!Initialize a user-allocated dvbpsi_pat_t structure.
- * \param p_pat PAT structure
+/*!
+ * \fn void dvbpsi_InitPAT(dvbpsi_pat_t* p_pat, uint16_t i_ts_id,
+                           uint8_t i_version, int b_current_next)
+ * \brief Initialize a user-allocated dvbpsi_pat_t structure.
+ * \param p_pat pointer to the PAT structure
  * \param i_ts_id transport stream ID
  * \param i_version PAT version
  * \param b_current_next current next indicator
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_InitPAT(dvbpsi_pat_t* p_pat, uint16_t i_ts_id, uint8_t i_version,
                     int b_current_next);
 
-/*!Allocate and initialize a new dvbpsi_pat_t structure.
- * \param p_pat PAT structure
+/*!
+ * \def dvbpsi_NewPAT(p_pat, i_ts_id, i_version, b_current_next)
+ * \brief Allocate and initialize a new dvbpsi_pat_t structure.
+ * \param p_pat pointer to the PAT structure
  * \param i_ts_id transport stream ID
  * \param i_version PAT version
  * \param b_current_next current next indicator
  * \return nothing.
- *****************************************************************************/
+ */
 #define dvbpsi_NewPAT(p_pat, i_ts_id, i_version, b_current_next)        \
   p_pat = (dvbpsi_pat_t*)malloc(sizeof(dvbpsi_pat_t));                  \
   if(p_pat != NULL)                                                     \
@@ -125,16 +165,20 @@ void dvbpsi_InitPAT(dvbpsi_pat_t* p_pat, uint16_t i_ts_id, uint8_t i_version,
 /*****************************************************************************
  * dvbpsi_EmptyPAT/dvbpsi_DeletePAT
  *****************************************************************************/
-/*!Clean a dvbpsi_pat_t structure.
- * \param p_pat PAT structure
+/*!
+ * \fn void dvbpsi_EmptyPAT(dvbpsi_pat_t* p_pat)
+ * \brief Clean a dvbpsi_pat_t structure.
+ * \param p_pat pointer to the PAT structure
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_EmptyPAT(dvbpsi_pat_t* p_pat);
 
-/*!Clean and free a dvbpsi_pat_t structure.
- * \param p_pat PAT structure
+/*!
+ * \def dvbpsi_DeletePAT(p_pat)
+ * \brief Clean and free a dvbpsi_pat_t structure.
+ * \param p_pat pointer to the PAT structure
  * \return nothing.
- *****************************************************************************/
+ */
 #define dvbpsi_DeletePAT(p_pat)                                         \
   dvbpsi_EmptyPAT(p_pat);                                               \
   free(p_pat);
@@ -143,24 +187,33 @@ void dvbpsi_EmptyPAT(dvbpsi_pat_t* p_pat);
 /*****************************************************************************
  * dvbpsi_PATAddProgram
  *****************************************************************************/
-/*!Add a program at the end of the PAT.
- * \param p_pat PAT structure
+/*!
+ * \fn dvbpsi_pat_program_t* dvbpsi_PATAddProgram(dvbpsi_pat_t* p_pat,
+                                                  uint16_t i_number,
+                                                  uint16_t i_pid)
+ * \brief Add a program at the end of the PAT.
+ * \param p_pat pointer to the PAT structure
  * \param i_number program number
  * \param i_pid PID of the NIT/PMT
  * \return a pointer to the added program.
- *****************************************************************************/
+ */
 dvbpsi_pat_program_t* dvbpsi_PATAddProgram(dvbpsi_pat_t* p_pat,
                                            uint16_t i_number, uint16_t i_pid);
 
 /*****************************************************************************
  * dvbpsi_GenPATSections
  *****************************************************************************/
-/*!Generate PAT sections based on the dvbpsi_pat_t structure.
- * \param p_pat PAT structure
+/*!
+ * \fn dvbpsi_psi_section_t* dvbpsi_GenPATSections(dvbpsi_pat_t* p_pat,
+                                                   int i_max_pps);
+ * \brief PAT generator.
+ * \param p_pat pointer to the PAT structure
  * \param i_max_pps limitation of the number of program in each section
  * (max: 253).
  * \return a pointer to the list of generated PSI sections.
- *****************************************************************************/
+ *
+ * Generate PAT sections based on the dvbpsi_pat_t structure.
+ */
 dvbpsi_psi_section_t* dvbpsi_GenPATSections(dvbpsi_pat_t* p_pat,
                                             int i_max_pps);
 

src/tables/pmt.h

 /*****************************************************************************
- * pmt.h: PMT structures
- *----------------------------------------------------------------------------
+ * pmt.h
  * (c)2001-2002 VideoLAN
- * $Id: pmt.h,v 1.4 2002/03/25 21:00:50 bozo Exp $
+ * $Id: pmt.h,v 1.5 2002/03/27 20:02:43 bozo Exp $
  *
  * Authors: Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
  *
@@ -20,10 +19,20 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  *
- *----------------------------------------------------------------------------
- *
  *****************************************************************************/
 
+/*!
+ * \file <pmt.h>
+ * \author Arnaud de Bossoreille de Ribou <bozo@via.ecp.fr>
+ * \brief Application interface for the PMT decoder and the PMT generator.
+ *
+ * Application interface for the PMT decoder and the PMT generator. New
+ * decoded PMT tables are sent by callback to the application. If a table
+ * wasn't active (b_current_next == 0) and the next is the same but active
+ * (b_current_next == 1) then the two lists are empty and should be
+ * caught from the previous structure.
+ */
+
 #ifndef _DVBPSI_PMT_H_
 #define _DVBPSI_PMT_H_
 
@@ -35,9 +44,17 @@ extern "C" {
 /*****************************************************************************
  * dvbpsi_pmt_es_t
  *****************************************************************************/
-/*!This structure is used to store a decoded ES description.
+/*!
+ * \struct dvbpsi_pmt_es_s
+ * \brief PMT ES structure.
+ *
+ * This structure is used to store a decoded ES description.
  * (ISO/IEC 13818-1 section 2.4.4.8).
- *****************************************************************************/
+ */
+/*!
+ * \typedef struct dvbpsi_pmt_es_s dvbpsi_pmt_es_t
+ * \brief dvbpsi_pmt_es_t type definition.
+ */
 typedef struct dvbpsi_pmt_es_s
 {
   uint8_t                       i_type;                 /*!< stream_type */
@@ -54,9 +71,17 @@ typedef struct dvbpsi_pmt_es_s
 /*****************************************************************************
  * dvbpsi_pmt_t
  *****************************************************************************/
-/*!This structure is used to store a decoded PMT.
+/*!
+ * \struct dvbpsi_pmt_s
+ * \brief PMT structure.
+ *
+ * This structure is used to store a decoded PMT.
  * (ISO/IEC 13818-1 section 2.4.4.8).
- *****************************************************************************/
+ */
+/*!
+ * \typedef struct dvbpsi_pmt_s dvbpsi_pmt_t
+ * \brief dvbpsi_pmt_t type definition.
+ */
 typedef struct dvbpsi_pmt_s
 {
   uint16_t                  i_program_number;   /*!< program_number */
@@ -75,20 +100,27 @@ typedef struct dvbpsi_pmt_s
 /*****************************************************************************
  * dvbpsi_pmt_callback
  *****************************************************************************/
-/*!Callback type definition.
- *****************************************************************************/
+/*!
+ * \typedef void (* dvbpsi_pmt_callback)(void* p_cb_data,
+                                         dvbpsi_pmt_t* p_new_pmt)
+ * \brief Callback type definition.
+ */
 typedef void (* dvbpsi_pmt_callback)(void* p_cb_data, dvbpsi_pmt_t* p_new_pmt);
 
 
 /*****************************************************************************
  * dvbpsi_AttachPMT
  *****************************************************************************/
-/*!Initialize a PMT decoder and return a handle on it.
+/*!
+ * \fn dvbpsi_handle dvbpsi_AttachPMT(uint16_t i_program_number,
+                                      dvbpsi_pmt_callback pf_callback,
+                                      void* p_cb_data)
+ * \brief Creation and initialization of a PMT decoder.
  * \param i_program_number program number
  * \param pf_callback function to call back on new PMT
  * \param p_cb_data private data given in argument to the callback
  * \return a pointer to the decoder for future calls.
- *****************************************************************************/
+ */
 dvbpsi_handle dvbpsi_AttachPMT(uint16_t i_program_number,
                                dvbpsi_pmt_callback pf_callback,
                                void* p_cb_data);
@@ -97,35 +129,46 @@ dvbpsi_handle dvbpsi_AttachPMT(uint16_t i_program_number,
 /*****************************************************************************
  * dvbpsi_DetachPMT
  *****************************************************************************/
-/*!Close a PMT decoder. The handle isn't valid any more.
+/*!
+ * \fn void dvbpsi_DetachPMT(dvbpsi_handle h_dvbpsi)
+ * \brief Destroy a PMT decoder.
  * \param h_dvbpsi handle to the decoder
  * \return nothing.
- *****************************************************************************/
+ *
+ * The handle isn't valid any more.
+ */
 void dvbpsi_DetachPMT(dvbpsi_handle h_dvbpsi);
 
 
 /*****************************************************************************
  * dvbpsi_InitPMT/dvbpsi_NewPMT
  *****************************************************************************/
-/*!Initialize a user-allocated dvbpsi_pmt_t structure.
- * \param p_pmt PMT structure
+/*!
+ * \fn void dvbpsi_InitPMT(dvbpsi_pmt_t* p_pmt, uint16_t i_program_number,
+                           uint8_t i_version, int b_current_next,
+                           uint16_t i_pcr_pid)
+ * \brief Initialize a user-allocated dvbpsi_pmt_t structure.
+ * \param p_pmt pointer to the PMT structure
  * \param i_program_number program number
  * \param i_version PMT version
  * \param b_current_next current next indicator
  * \param i_pcr_pid PCR_PID
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_InitPMT(dvbpsi_pmt_t* p_pmt, uint16_t i_program_number,
                     uint8_t i_version, int b_current_next, uint16_t i_pcr_pid);
 
-/*!Allocate and initialize a new dvbpsi_pmt_t structure.
- * \param p_pmt PMT structure
+/*!
+ * \def dvbpsi_NewPMT(p_pmt, i_program_number,
+                      i_version, b_current_next, i_pcr_pid)
+ * \brief Allocate and initialize a new dvbpsi_pmt_t structure.
+ * \param p_pmt pointer to the PMT structure
  * \param i_program_number program number
  * \param i_version PMT version
  * \param b_current_next current next indicator
  * \param i_pcr_pid PCR_PID
  * \return nothing.
- *****************************************************************************/
+ */
 #define dvbpsi_NewPMT(p_pmt, i_program_number,                          \
                       i_version, b_current_next, i_pcr_pid)             \
   p_pmt = (dvbpsi_pmt_t*)malloc(sizeof(dvbpsi_pmt_t));                  \
@@ -137,16 +180,20 @@ void dvbpsi_InitPMT(dvbpsi_pmt_t* p_pmt, uint16_t i_program_number,
 /*****************************************************************************
  * dvbpsi_EmptyPMT/dvbpsi_DeletePMT
  *****************************************************************************/
-/*!Clean a dvbpsi_pmt_t structure.
- * \param p_pmt PMT structure
+/*!
+ * \fn void dvbpsi_EmptyPMT(dvbpsi_pmt_t* p_pmt)
+ * \brief Clean a dvbpsi_pmt_t structure.
+ * \param p_pmt pointer to the PMT structure
  * \return nothing.
- *****************************************************************************/
+ */
 void dvbpsi_EmptyPMT(dvbpsi_pmt_t* p_pmt);
 
-/*!Clean and free a dvbpsi_pmt_t structure.
- * \param p_pmt PMT structure
+/*!
+ * \def dvbpsi_DeletePMT(p_pmt)
+ * \brief Clean and free a dvbpsi_pmt_t structure.
+ * \param p_pmt pointer to the PMT structure
  * \return nothing.
- *****************************************************************************/
+ */
 #define dvbpsi_DeletePMT(p_pmt)                                         \
   dvbpsi_EmptyPMT(p_pmt);                                               \
   free(p_pmt);
@@ -155,13 +202,18 @@ void dvbpsi_EmptyPMT(dvbpsi_pmt_t* p_pmt);
 /*****************************************************************************
  * dvbpsi_PMTAddDescriptor
  *****************************************************************************/
-/*!Add a descriptor in the PMT.
- * \param p_pmt PMT structure
+/*!
+ * \fn dvbpsi_descriptor_t* dvbpsi_PMTAddDescriptor(dvbpsi_pmt_t* p_pmt,
+                                                    uint8_t i_tag,
+                                                    uint8_t i_length,
+                                                    uint8_t* p_data)
+ * \brief Add a descriptor in the PMT.
+ * \param p_pmt pointer to the PMT structure
  * \param i_tag descriptor's tag
  * \param i_length descriptor's length
  * \param p_data descriptor's data
  * \return a pointer to the added descriptor.
- *****************************************************************************/
+ */
 dvbpsi_descriptor_t* dvbpsi_PMTAddDescriptor(dvbpsi_pmt_t* p_pmt,
                                              uint8_t i_tag, uint8_t i_length,
                                              uint8_t* p_data);
@@ -170,12 +222,15 @@ dvbpsi_descriptor_t* dvbpsi_PMTAddDescriptor(dvbpsi_pmt_t* p_pmt,
 /*****************************************************************************
  * dvbpsi_PMTAddES
  *****************************************************************************/
-/*!Add an ES in the PMT.
- * \param p_pmt PMT structure
+/*!
+ * \fn dvbpsi_pmt_es_t* dvbpsi_PMTAddES(dvbpsi_pmt_t* p_pmt,
+                                        uint8_t i_type, uint16_t i_pid)
+ * \brief Add an ES in the PMT.
+ * \param p_pmt pointer to the PMT structure
  * \param i_type type of ES
  * \param i_pid PID of the ES
  * \return a pointer to the added ES.
- *****************************************************************************/
+ */
 dvbpsi_pmt_es_t* dvbpsi_PMTAddES(dvbpsi_pmt_t* p_pmt,
                                  uint8_t i_type, uint16_t i_pid);
 
@@ -183,13 +238,18 @@ dvbpsi_pmt_es_t* dvbpsi_PMTAddES(dvbpsi_pmt_t* p_pmt,
 /*****************************************************************************
  * dvbpsi_PMTESAddDescriptor
  *****************************************************************************/
-/*!Add a descriptor in the PMT ES.
- * \param p_es ES structure
+/*!
+ * \fn dvbpsi_descriptor_t* dvbpsi_PMTESAddDescriptor(dvbpsi_pmt_es_t* p_es,
+                                                      uint8_t i_tag,
+                                                      uint8_t i_length,
+                                                      uint8_t* p_data)
+ * \brief Add a descriptor in the PMT ES.
+ * \param p_es pointer to the ES structure
  * \param i_tag descriptor's tag
  * \param i_length descriptor's length
  * \param p_data descriptor's data
  * \return a pointer to the added descriptor.
- *****************************************************************************/
+ */
 dvbpsi_descriptor_t* dvbpsi_PMTESAddDescriptor(dvbpsi_pmt_es_t* p_es,
                                                uint8_t i_tag, uint8_t i_length,
                                                uint8_t* p_data);
@@ -198,10 +258,14 @@ dvbpsi_descriptor_t* dvbpsi_PMTESAddDescriptor(dvbpsi_pmt_es_t* p_es,
 /*****************************************************************************
  * dvbpsi_GenPMTSections
  *****************************************************************************/
-/*!Generate PMT sections based on the dvbpsi_pmt_t structure.
+/*!
+ * \fn dvbpsi_psi_section_t* dvbpsi_GenPMTSections(dvbpsi_pmt_t* p_pmt)
+ * \brief PMT generator
  * \param p_pmt PMT structure
  * \return a pointer to the list of generated PSI sections.
- *****************************************************************************/
+ *
+ * Generate PMT sections based on the dvbpsi_pmt_t structure.
+ */
 dvbpsi_psi_section_t* dvbpsi_GenPMTSections(dvbpsi_pmt_t* p_pmt);