Skip to content

L
libdvbpsi
Commit 9982ebce authored by Jean-Paul Saman's avatar Jean-Paul Saman
Browse files
Options

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

parent 93f02c8d
Hide whitespace changes
Inline Side-by-side
Showing with 226 additions and 0 deletions
doc/index.doxygen
View file @ 9982ebce
......@@ -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 0 → 100644
View file @ 9982ebce
/*! \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>
*/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment