<br><br><div class="gmail_quote">On Sat, Dec 19, 2009 at 7:27 PM, Christophe Massiot <span dir="ltr"><<a href="mailto:massiot@via.ecp.fr">massiot@via.ecp.fr</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Dear all,<br>
<br>
We have been discussing the future of libdvbpsi at the VideoLAN Dev Days<br>
with jpsaman and gatty, and we would like to propose a number of API<br>
changes for libdvbpsi, and release them as version 1.0. The main goals<br>
of theses changes are :<br>
<br>
1/ To avoid breaking the API and ABI every time we add support for a new<br>
descriptor or table.<br>
2/ To move semantics out of libdvbpsi into the application and keep<br>
libdvbpsi a basic table parser.<br>
3/ To make the API more symmetrical wrt. inputs and outputs of libdvbpsi.<br>
<br>
#############################################################<br>
# Goal #2 involves a major API change and a modification of #<br>
# applications so please keep on reading !!! #<br>
#############################################################<br>
<br>
<br>
1/ To avoid breaking the API and ABI at every new table, we first<br>
propose to make a few helper functions inline, for instance :<br>
dvbpsi_InitPMT()<br>
dvbpsi_EmptyPMT()<br>
dvbpsi_PMTESAdd(), dvbpsi_PMTAddDescriptor(), etc.<br>
(same for other tables)<br>
<br>
These functions only operate on local structures and are quite small ;<br>
they have no links with the rest of libdvbpsi. IMHO they are not quite<br>
useful since you can change the fields in the structure yourself, but<br>
whatever. They exist and are used in the field.<br>
<br>
For the descriptors we propose a second strategy. We define two generic<br>
functions, whose first parameter is a descriptor type :<br>
dvbpsi_handle dvbpsi_DecodeDescriptor( int i_descriptor_type, dvbpsi_descriptor_t * )<br>
dvbpsi_descriptor_t *dvbpsi_GenDescriptor( int i_descriptor_type, dvbpsi_handle *p_decoded, int b_duplicate )<br></blockquote><div><br>TO keep it symmetric I propose to use dvbpsi_GenerateDescriptor() as we use dvbpsi_DecodeDescriptor(). Either use abreviations everywhere or write them out.<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
And then we rewrite all the descriptor-specific functions as such :<br>
#define dvbpsi_DecodeISO639Dr(x) (dvbpsi_iso639_dr_t *)dvbpsi_DecodeDescriptor(ISO639_DR, x)<br>
#define dvbpsi_GenISO639Dr(x, y) dvbpsi_GenDescriptor(ISO639_DR, x, y)<br>
<br>
Note that all changes proposed in #1 are source-compatible with 0.1.6.<br>
<br>
<br>
2/ The same problem arises with the Attach* and Detach* functions, but<br>
more difficult to solve because they have a variable number of arguments<br>
depending on the tables. The arguments are used to set filters on events<br>
that you want, like a program number or a table ID.<br>
<br>
We propose to drop this filtering support from libdvbpsi. It can<br>
easily be done application-side, in the callback. That way, the new API<br>
would just look like :<br>
dvbpsi_handle dvbpsi_AttachTable(int i_table_type, dvbpsi_callback pf_callback, void *p_cb_data)<br>
void dvbpsi_DetachTable(dvbpsi_handle h_dvbpsi, int i_table_type)<br>
<br>
However existing applications need to be adapted to the new behaviour.<br>
That is, you must have on top of your callback :<br>
if (p_pmt->i_program_number != i_my_program)<br>
{<br>
dvbpsi_DeletePMT( p_pmt );<br>
return;<br>
}<br>
and the equivalent for other tables.<br></blockquote><div><br>I we use wrapper functions for this anyway, them we can add this generic part of code too. This will keep existing semantics.<br> <br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Also at the same time I'd like to drop the check on the version of the<br>
tables. In my experience there are many cases where the table is changed<br>
and the version_number isn't. I know it isn't compliant, but we have to<br>
deal with this case. So if you want the old behaviour you'd have to add<br>
on top of the callback :<br>
if (p_pmt->i_version == i_previous_version)<br>
{<br>
dvbpsi_DeletePMT( p_pmt );<br>
return;<br>
}<br>
<br>
Again, this proposed change is NOT source-compatible with 0.1.6.<br>
<br>
<br>
3/ All application projects duplicate the same lines of code, generally<br>
called "WritePSISection", to split a PSI section into transport stream<br>
packets. Since libdvbpsi's input is TS packets, it seems logical to be<br>
able to output TS packets. We therefore propose to add an extra API that<br>
would look like :<br>
<br>
int dvbpsi_HowManyTSBuffers(dvbpsi_section_t *)<br>
(merely returns (size + 183) / 184)<br>
int dvbpsi_GenTS( uint8_t *pp_ts_buffers[], int i_nb_buffers,<br>
dvbpsi_section_t *, uint16_t i_pid, uint8_t *pi_cc )<br>
<br>
This change is source-compatible with 0.1.6 because it only adds new<br>
functions.<br>
<br>
<br>
Conclusions :<br>
If you have a great idea, or a strong opposition to the ideas presented<br>
here, please share.<br>
<br>
Kind hugs to everybody,<br>
<font color="#888888">--<br>
Christophe Massiot.<br>
_______________________________________________<br>
libdvbpsi-devel mailing list<br>
<a href="mailto:libdvbpsi-devel@videolan.org">libdvbpsi-devel@videolan.org</a><br>
<a href="http://mailman.videolan.org/listinfo/libdvbpsi-devel" target="_blank">http://mailman.videolan.org/listinfo/libdvbpsi-devel</a><br>
</font></blockquote></div><br>Kind regards,<br><br>Jean-Paul Saman<br>