Doxygen: write documentation for migrating to libdvbpsi version 2.0.0 from previous versions.

doc/index.doxygen

@@ -53,6 +53,7 @@ describes how to use it and the "C" API.</p>
   <li>\ref usage</li>
   <li>\ref newdec</li>
   <li>\ref howto-new-api</li>
+  <li>\ref migrate-v1-to-v2</li>
 </ul>
 
 */

doc/migrate-v1-to-v2.doxygen

+/*! \page migrate-v1-to-v2 Migrate from dvbpsi API version 1.0.0 to version 2.0.0
+
+<p>In libdvbpsi version 2 the API has changed considerably in the area of subtable decoders.
+Upto version 1.x.x this was handled by demux functions (dvbpsi/demux.h). It required for
+each PSI subtable that a new dvbpsi_subsdec_t struct was used to wrap other subtable decoders.
+Not all PSI tables implemented that, such as PAT, PMT and CAT. The version 2 removes all
+demux_XXX functions and replaces it with a simple linked list implemented by dvbpsi_decoder_chain_XXX()
+functions. As a result all PSI Tables can be chained now and handled by only one demuxing
+function operating on a dvbpsi_t handle. It is still possible to allocate a dvbpsi_t handle
+per PSI table, which is compatible with the old way of working in writing libdvbpsi table decoders.</p>
+
+<h2>Example: PAT table</h2>
+
+<p>
+The following examples shows howto translate existing applications. In these examples only
+source code snippits are used and can thus not be compiled standalone. The examples are taken
+from existing applications using libdvbpsi. For a more elaborate example take a look in examples/ directory
+and especially to the file examples/dvbinfo/libdvbpsi.c from the dvbinfo application.
+</p>
+
+<p>In many existing applications the following scheme is used to attach a PAT decoder to a dvbpsi handle
+(This code is still supported by libdvbpsi version 2.0.0):</p>
+
+<code>
+&nbsp; dvbpsi_t *handle = dvbpsi_new(&dvbpsi_message, DVBPSI_MSG_DEBUG); <br />
+&nbsp; if (handle == NULL) <br />
+&nbsp;&nbsp; goto error; <br />
+&nbsp; if (!dvbpsi_pat_attach(handle, handle_PAT, data)) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; dvbpsi_delete(handle); <br />
+&nbsp; &nbsp; handle = NULL; <br />
+&nbsp; &nbsp; goto error; <br />
+&nbsp; } <br />
+&nbsp; ... other code ...
+&nbsp; <br />
+&nbsp; return 0; <br />
+&nbsp; <br />
+error: <br />
+&nbsp; if (dvbpsi_decoder_present(handle)) <br />
+&nbsp; &nbsp; dvbpsi_pat_detach(handle); <br />
+&nbsp; if (handle) <br />
+&nbsp; &nbsp;  dvbpsi_delete(handle); <br />
+&nbsp; return -1; <br />
+</code>
+
+<p>The same snippit of code using the dvbpsi_decoder_chain_XX() functions looks like this:</p>
+
+<code>
+/***************************************************************************** <br />
+&nbsp; * AttachPAT <br />
+&nbsp; *****************************************************************************/ <br />
+static void AttachPAT(dvbpsi_t *p_dvbpsi, uint8_t i_table_id, uint16_t i_extension, <br />
+&nbsp;                void *p_zero) <br />
+{ <br />
+&nbsp; if (!dvbpsi_pat_attach(p_dvbpsi, i_table_id, i_extension, DumpPAT, NULL)) <br />
+&nbsp; &nbsp; fprintf(stderr, "Failed to attach PAT decoder\n"); <br />
+} <br />
+<br />
+static void DetachPAT(dvbpsi_t *p_dvbpsi, uint8_t i_table_id, uint16_t i_extension) <br />
+{ <br />
+&nbsp; dvbpsi_pat_detach(p_dvbpsi, i_table_id, i_extension); <br />
+} <br />
+<br />
+void main(int argc, char** argv) <br />
+{ <br />
+&nbsp; dvbpsi_t *handle = dvbpsi_new(&dvbpsi_message, DVBPSI_MSG_DEBUG); <br />
+&nbsp; if (handle == NULL) <br />
+&nbsp; &nbsp; goto error; <br />
+&nbsp; &nbsp; if (!dvbpsi_decoder_chain_new(p_dvbpsi, AttachPAT, DetachPAT, NULL)) <br />
+&nbsp; &nbsp; goto error; <br />
+&nbsp; <br />
+&nbsp; .. other code .. <br />
+&nbsp; return 0; <br />
+ <br />
+error: &nbsp; <br />
+&nbsp; if (!dvbpsi_decoder_chain_delete(p_dvbpsi)) <br />
+&nbsp; &nbsp; goto error; <br />
+&nbsp; &nbsp;if (handle) <br />
+&nbsp; &nbsp; dvbpsi_delete(handle); <br />
+&nbsp; return -1; <br />
+} <br />
+</code>
+
+<h2>Example: Demuxing SDT table</h2>
+
+<p>The scheme used for demuxing PSI tables and subtables is very similar, but requires different APIs. With the
+new API (version 2 and up), the code looks the same as with the example above. The first code segment shows the
+old way of doing things. The second shows you how to write it with dvbpsi_decoder_chain_XXX() functions.</p>
+
+<code>
+/***************************************************************************** <br />
+&nbsp; * NewSubtable <br />
+&nbsp; *****************************************************************************/ <br />
+static void NewSubtable(dvbpsi_t *p_dvbpsi, uint8_t i_table_id, uint16_t i_extension, <br />
+&nbsp;                  void * p_zero) <br />
+{ <br />
+&nbsp; if (i_table_id == 0x42) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; if (!dvbpsi_sdt_attach(p_dvbpsi, i_table_id, i_extension, DumpSDT, NULL)) <br />
+&nbsp; &nbsp; &nbsp; fprintf(stderr, "Failed to attach SDT subdecoder\n"); <br />
+&nbsp; } <br />
+} <br />
+ <br />
+/***************************************************************************** <br />
+&nbsp; * main <br />
+&nbsp; *****************************************************************************/ <br />
+int main(int i_argc, char* pa_argv[]) <br />
+{ <br />
+&nbsp; int i_fd; <br />
+&nbsp; int ret = 1; <br />
+&nbsp; uint8_t data[188]; <br />
+&nbsp; dvbpsi_t *p_dvbpsi; <br />
+&nbsp; bool b_ok; <br />
+ <br />
+&nbsp; if(i_argc != 2) <br />
+&nbsp; &nbsp; return 1; <br />
+ <br />
+&nbsp; i_fd = open(pa_argv[1], 0); <br />
+&nbsp; if (i_fd < 0) <br />
+&nbsp; &nbsp; return 1; <br />
+ <br />
+&nbsp; p_dvbpsi = dvbpsi_new(&message, DVBPSI_MSG_DEBUG); <br />
+&nbsp; if (p_dvbpsi == NULL) <br />
+&nbsp; &nbsp; goto out; <br />
+ <br />
+&nbsp; if (!dvbpsi_AttachDemux(p_dvbpsi, NewSubtable, NULL)) <br />
+&nbsp; &nbsp; goto out; <br />
+ <br />
+&nbsp; b_ok = ReadPacket(i_fd, data); <br />
+ <br />
+&nbsp; while(b_ok) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; uint16_t i_pid = ((uint16_t)(data[1] & 0x1f) << 8) + data[2]; <br />
+&nbsp; &nbsp; if(i_pid == 0x11) <br />
+&nbsp; &nbsp; &nbsp; dvbpsi_packet_push(p_dvbpsi, data); <br />
+&nbsp; &nbsp; b_ok = ReadPacket(i_fd, data); <br />
+&nbsp; } <br />
+ <br />
+&nbsp; ret = 0; <br />
+ <br />
+out: <br />
+&nbsp; if (p_dvbpsi) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; dvbpsi_DetachDemux(p_dvbpsi); <br />
+&nbsp; &nbsp; dvbpsi_delete(p_dvbpsi); <br />
+&nbsp; } <br />
+&nbsp; close(i_fd); <br />
+&nbsp; return ret; <br />
+} <br />
+<code>
+
+<code>
+/***************************************************************************** <br />
+&nbsp; * NewSubtable <br />
+&nbsp; *****************************************************************************/ <br />
+static void NewSubtable(dvbpsi_t *p_dvbpsi, uint8_t i_table_id, uint16_t i_extension, <br />
+&nbsp;                  void * p_zero) <br />
+{ <br />
+&nbsp; if(i_table_id == 0x42) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; if (!dvbpsi_sdt_attach(p_dvbpsi, i_table_id, i_extension, DumpSDT, NULL)) <br />
+&nbsp; &nbsp; &nbsp; fprintf(stderr, "Failed to attach SDT subdecoder\n"); <br />
+&nbsp; } <br />
+} <br />
+ <br />
+/***************************************************************************** <br />
+&nbsp; * DelSubtable <br />
+&nbsp; *****************************************************************************/ <br />
+static void DelSubtable(dvbpsi_t *p_dvbpsi, uint8_t i_table_id, uint16_t i_extension) <br />
+{ <br />
+&nbsp; if(i_table_id == 0x42) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; dvbpsi_sdt_detach(p_dvbpsi, i_table_id, i_extension); <br />
+&nbsp; } <br />
+} <br />
+ <br />
+/***************************************************************************** <br />
+&nbsp; * main <br />
+&nbsp; *****************************************************************************/ <br />
+int main(int i_argc, char* pa_argv[]) <br />
+{ <br />
+&nbsp; int i_fd; <br />
+&nbsp; int ret = 1; <br />
+&nbsp; uint8_t data[188]; <br />
+&nbsp; dvbpsi_t *p_dvbpsi; <br />
+&nbsp; bool b_ok; <br />
+ <br />
+&nbsp; if(i_argc != 2) <br />
+&nbsp; &nbsp; return 1; <br />
+ <br />
+&nbsp; i_fd = open(pa_argv[1], 0); <br />
+&nbsp; if (i_fd < 0) <br />
+&nbsp; &nbsp; return 1; <br />
+ <br />
+&nbsp; p_dvbpsi = dvbpsi_new(&message, DVBPSI_MSG_DEBUG); <br />
+&nbsp; if (p_dvbpsi == NULL) <br />
+&nbsp; &nbsp; goto out; <br />
+ <br />
+&nbsp; if (!dvbpsi_decoder_chain_new(p_dvbpsi, NewSubtable, DelSubtable, NULL)) <br />
+&nbsp; &nbsp; goto out; <br />
+ <br />
+&nbsp; b_ok = ReadPacket(i_fd, data); <br />
+ <br />
+&nbsp; while(b_ok) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; uint16_t i_pid = ((uint16_t)(data[1] & 0x1f) << 8) + data[2]; <br />
+&nbsp; &nbsp; if(i_pid == 0x11) <br />
+&nbsp; &nbsp; &nbsp; dvbpsi_packet_push(p_dvbpsi, data); <br />
+&nbsp; &nbsp; b_ok = ReadPacket(i_fd, data); <br />
+&nbsp; } <br />
+ <br />
+&nbsp; ret = 0; <br />
+ <br />
+out: <br />
+&nbsp; if (p_dvbpsi) <br />
+&nbsp; { <br />
+&nbsp; &nbsp; if (!dvbpsi_decoder_chain_delete(p_dvbpsi)) <br />
+&nbsp; &nbsp; &nbsp; ret = 1; <br />
+&nbsp; &nbsp; dvbpsi_delete(p_dvbpsi); <br />
+&nbsp; } <br />
+&nbsp; close(i_fd); <br />
+&nbsp; return ret; <br />
+} <br />
+</code>
+*/