Commit 79b28353 authored by Jean-Paul Saman's avatar Jean-Paul Saman

doc/howto-new-api: add new API description.

Add a description on howto translate the old API into the new (update) API.
parent 1ac4cd61
## Process this file with automake to produce Makefile.in
EXTRA_DIST=index.doxygen structure.doxygen usage.doxygen newdec.doxygen \
howto-new-api.doxygen \
decoder.dot doxygen.cfg
MOSTLYCLEANFILES=decoder.png
......
......@@ -585,6 +585,7 @@ INPUT = index.doxygen \
structure.doxygen \
usage.doxygen \
newdec.doxygen \
howto-new-api.doxygen \
../src \
../src/tables \
../src/descriptors
......
/*! \page Howto port dvbpsi API (upto version 0.2.0) to version 1.0.0
<p>An update to libdvbpsi API was long overdue. In time the API grew to be inconsistent and
needed some cleanup. The following issue are addressed in this version:</p>
<ul>
<li>explicit library handle allocation with <em>dvbpsi_NewHandle()</em> (delete with <em>dvbpsi_DeleteHandle()</em>)</li>
<li>consistent API for table and descriptor decoder/encoders</li>
<li>message callback function for easier intergrating libdvbpsi logging in applications</li>
</ul>
<p>The biggest change is the addition off an explicit dvbpsi_t pointer to
ALL table decoder and encoder API's. This dvbpsi_t pointer is a dvbpsi handle
which must be allocated using <em>dvbpsi_NewHandle()</em> and takes a callback function
for logging.
</p>
<code>dvbpsi_t *dvbpsi_NewHandle(dvbpsi_message_cb callback, enum dvbpsi_msg_level level);</code>
<p>The dvbpsi_t pointer must be released by calling <em>dvbpsi_DeleteHandle()</em></p>
<code>void dvbpsi_DeleteHandle(dvbpsi_t *handle);</code>
<h2>Example</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.
</p>
<p>In many existing applications the following scheme is used to attaching a PAT decoder to a dvbpsi handle:</p>
<code>
dvbpsi_handle handle;
dvbpsi_AttachPAT(handle, handle_PAT, data);
</code>
<p>The same scheme is used for other PSI tables too, this translate to the following code sequence:</p>
<code>
dvbpsi_t *handle = dvbpsi_NewHandle(&dvbpsi_message, DVBPSI_MSG_DEBUG);
if (handle == NULL)
goto error;
if (!dvbpsi_AttachPAT(handle, handle_PAT, data))
{
dvbpsi_DeleteHandle(handle);
handle = NULL;
goto error;
}
return 0;
error:
if (dvbpsi_HasDecoder(handle))
dvbpsi_DetachPAT(andle);
if (handle)
dvbpsi_DeleteHandle(handle);
return -1;
</code>
<p>The <em>message callback function</em> <b>dvbpsi_message</b> is defined as follows below. In this case
the output goes directly to the console. Applications however can call into their messaging API and pass
along libdvbpsi messages if wanted.
</p>
<code>
static void dvbpsi_message(dvbpsi_t *p_dvbpsi, const dvbpsi_msg_level_t level, const char* msg)
{
switch(level)
{
case DVBPSI_MSG_ERROR: fprintf(stderr, "Error: "); break;
case DVBPSI_MSG_WARN: fprintf(stderr, "Warning: "); break;
case DVBPSI_MSG_DEBUG: fprintf(stderr, "Debug: "); break;
default:
return;
}
fprintf(stderr, "%s\n", msg);
}
</code>
*/
......@@ -46,6 +46,7 @@ describes how to use it and the "C" API.</p>
<li>\ref structure</li>
<li>\ref usage</li>
<li>\ref newdec</li>
<li>\ref howto-new-api</li>
</ul>
*/
......@@ -29,4 +29,6 @@ tables.</p>
\ref usage
\ref howto-new-api
*/
......@@ -41,4 +41,6 @@ file:</p>
\ref structure
\ref howto-new-api
*/
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