1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Demux Callback API</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="dvb_kdapi.html" title="Chapter 15. Kernel Demux API"><link rel="prev" href="demux_api.html" title="Demux API"><link rel="next" href="ts_feed_api.html" title="TS Feed API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Demux Callback API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="demux_api.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Demux API</th><td width="20%" align="right"> <a accesskey="n" href="ts_feed_api.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="demux_callback_api"></a>Demux Callback API</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="demux_callback_api.html#idp1130918892">dmx_ts_cb()</a></span></dt><dt><span class="section"><a href="demux_callback_api.html#idp1130939420">dmx_section_cb()</a></span></dt></dl></div><p>This kernel-space API comprises the callback functions that deliver filtered data to the 2demux client. Unlike the other APIs, these API functions are provided by the client and called 3from the demux code. 4</p><p>The function pointers of this abstract interface are not packed into a structure as in the 5other demux APIs, because the callback functions are registered and used independent 6of each other. As an example, it is possible for the API client to provide several 7callback functions for receiving TS packets and no callbacks for PES packets or 8sections. 9</p><p>The functions that implement the callback API need not be re-entrant: when a demux 10driver calls one of these functions, the driver is not allowed to call the function again before 11the original call returns. If a callback is triggered by a hardware interrupt, it is recommended 12to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback 13function call directly from a hardware interrupt. 14</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1130918892"></a>dmx_ts_cb()</h3></div></div></div><p>DESCRIPTION 15</p><div class="informaltable"><table border="1"><colgroup><col></colgroup><tbody><tr><td align="char"> 16<p>This function, provided by the client of the demux API, is called from the 17 demux code. The function is only called when filtering on this TS feed has 18 been enabled using the start_filtering() function.</p> 19</td></tr><tr><td align="char"> 20<p>Any TS packets that match the filter settings are copied to a circular buffer. The 21 filtered TS packets are delivered to the client using this callback function. The 22 size of the circular buffer is controlled by the circular_buffer_size parameter 23 of the set() function in the TS Feed API. It is expected that the buffer1 and 24 buffer2 callback parameters point to addresses within the circular buffer, but 25 other implementations are also possible. Note that the called party should not 26 try to free the memory the buffer1 and buffer2 parameters point to.</p> 27</td></tr><tr><td align="char"> 28<p>When this function is called, the buffer1 parameter typically points to the 29 start of the first undelivered TS packet within a circular buffer. The buffer2 30 buffer parameter is normally NULL, except when the received TS packets have 31 crossed the last address of the circular buffer and ”wrapped” to the beginning 32 of the buffer. In the latter case the buffer1 parameter would contain an address 33 within the circular buffer, while the buffer2 parameter would contain the first 34 address of the circular buffer.</p> 35</td></tr><tr><td align="char"> 36<p>The number of bytes delivered with this function (i.e. buffer1_length + 37 buffer2_length) is usually equal to the value of callback_length parameter 38 given in the set() function, with one exception: if a timeout occurs before 39 receiving callback_length bytes of TS data, any undelivered packets are 40 immediately delivered to the client by calling this function. The timeout 41 duration is controlled by the set() function in the TS Feed API.</p> 42</td></tr><tr><td align="char"> 43<p>If a TS packet is received with errors that could not be fixed by the TS-level 44 forward error correction (FEC), the Transport_error_indicator flag of the TS 45 packet header should be set. The TS packet should not be discarded, as 46 the error can possibly be corrected by a higher layer protocol. If the called 47 party is slow in processing the callback, it is possible that the circular buffer 48 eventually fills up. If this happens, the demux driver should discard any TS 49 packets received while the buffer is full. The error should be indicated to the 50 client on the next callback by setting the success parameter to the value of 51 DMX_OVERRUN_ERROR.</p> 52</td></tr><tr><td align="char"> 53<p>The type of data returned to the callback can be selected by the new 54 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t 55 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the 56 include file ost/demux.h) The type parameter decides if the raw TS packet 57 (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) 58 should be returned. If additionally the TS_DECODER bit is set the stream 59 will also be sent to the hardware MPEG decoder. In this case, the second 60 flag decides as what kind of data the stream should be interpreted. The 61 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, 62 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, 63 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</p> 64</td></tr></tbody></table></div><p>SYNOPSIS 65</p><div class="informaltable"><table border="1"><colgroup><col></colgroup><tbody><tr><td align="char"> 66<p>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, 67 __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ 68 source, dmx_success_t success);</p> 69</td></tr></tbody></table></div><p>PARAMETERS 70</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td align="char"> 71<p>__u8* buffer1</p> 72</td><td align="char"> 73<p>Pointer to the start of the filtered TS packets.</p> 74</td></tr><tr><td align="char"> 75<p>size_t buffer1_length</p> 76</td><td align="char"> 77<p>Length of the TS data in buffer1.</p> 78</td></tr><tr><td align="char"> 79<p>__u8* buffer2</p> 80</td><td align="char"> 81<p>Pointer to the tail of the filtered TS packets, or NULL.</p> 82</td></tr><tr><td align="char"> 83<p>size_t buffer2_length</p> 84</td><td align="char"> 85<p>Length of the TS data in buffer2.</p> 86</td></tr><tr><td align="char"> 87<p>dmx_ts_feed_t* 88 source</p> 89</td><td align="char"> 90<p>Indicates which TS feed is the source of the callback.</p> 91</td></tr><tr><td align="char"> 92<p>dmx_success_t 93 success</p> 94</td><td align="char"> 95<p>Indicates if there was an error in TS reception.</p> 96</td></tr></tbody></table></div><p>RETURNS 97</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td align="char"> 98<p>0</p> 99</td><td align="char"> 100<p>Continue filtering.</p> 101</td></tr><tr><td align="char"> 102<p>-1</p> 103</td><td align="char"> 104<p>Stop filtering - has the same effect as a call to 105 stop_filtering() on the TS Feed API.</p> 106</td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1130939420"></a>dmx_section_cb()</h3></div></div></div><p>DESCRIPTION 107</p><div class="informaltable"><table border="1"><colgroup><col></colgroup><tbody><tr><td align="char"> 108<p>This function, provided by the client of the demux API, is called from the 109 demux code. The function is only called when filtering of sections has been 110 enabled using the function start_filtering() of the section feed API. When the 111 demux driver has received a complete section that matches at least one section 112 filter, the client is notified via this callback function. Normally this function is 113 called for each received section; however, it is also possible to deliver multiple 114 sections with one callback, for example when the system load is high. If an 115 error occurs while receiving a section, this function should be called with 116 the corresponding error type set in the success field, whether or not there is 117 data to deliver. The Section Feed implementation should maintain a circular 118 buffer for received sections. However, this is not necessary if the Section Feed 119 API is implemented as a client of the TS Feed API, because the TS Feed 120 implementation then buffers the received data. The size of the circular buffer 121 can be configured using the set() function in the Section Feed API. If there 122 is no room in the circular buffer when a new section is received, the section 123 must be discarded. If this happens, the value of the success parameter should 124 be DMX_OVERRUN_ERROR on the next callback.</p> 125</td></tr></tbody></table></div><p>SYNOPSIS 126</p><div class="informaltable"><table border="1"><colgroup><col></colgroup><tbody><tr><td align="char"> 127<p>int dmx_section_cb(__u8⋆ buffer1, size_t 128 buffer1_length, __u8⋆ buffer2, size_t 129 buffer2_length, dmx_section_filter_t⋆ source, 130 dmx_success_t success);</p> 131</td></tr></tbody></table></div><p>PARAMETERS 132</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td align="char"> 133<p>__u8* buffer1</p> 134</td><td align="char"> 135<p>Pointer to the start of the filtered section, e.g. within the 136 circular buffer of the demux driver.</p> 137</td></tr><tr><td align="char"> 138<p>size_t buffer1_length</p> 139</td><td align="char"> 140<p>Length of the filtered section data in buffer1, including 141 headers and CRC.</p> 142</td></tr><tr><td align="char"> 143<p>__u8* buffer2</p> 144</td><td align="char"> 145<p>Pointer to the tail of the filtered section data, or NULL. 146 Useful to handle the wrapping of a circular buffer.</p> 147</td></tr><tr><td align="char"> 148<p>size_t buffer2_length</p> 149</td><td align="char"> 150<p>Length of the filtered section data in buffer2, including 151 headers and CRC.</p> 152</td></tr><tr><td align="char"> 153<p>dmx_section_filter_t* 154 filter</p> 155</td><td align="char"> 156<p>Indicates the filter that triggered the callback.</p> 157</td></tr><tr><td align="char"> 158<p>dmx_success_t 159 success</p> 160</td><td align="char"> 161<p>Indicates if there was an error in section reception.</p> 162</td></tr></tbody></table></div><p>RETURNS 163</p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td align="char"> 164<p>0</p> 165</td><td align="char"> 166<p>Continue filtering.</p> 167</td></tr><tr><td align="char"> 168<p>-1</p> 169</td><td align="char"> 170<p>Stop filtering - has the same effect as a call to 171 stop_filtering() on the Section Feed API.</p> 172</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="demux_api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dvb_kdapi.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ts_feed_api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Demux API </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> TS Feed API</td></tr></table></div></body></html> 173