This function is used to allocate a section filter on the demux. It should only be called when no filtering is in progress on this section feed. If a filter cannot be allocated, the function fails with -ENOSPC. See in section ?? for the format of the section filter.

The bitfields filter_mask and filter_value should only be modified when no filtering is in progress on this section feed. filter_mask controls which bits of filter_value are compared with the section headers/payload. On a binary value of 1 in filter_mask, the corresponding bits are compared. The filter only accepts sections that are equal to filter_value in all the tested bit positions. Any changes to the values of filter_mask and filter_value are guaranteed to take effect only when the start_filtering() function is called next time. The parent pointer in the struct is initialized by the API implementation to the value of the feed parameter. The priv pointer is not used by the API implementation, and can thus be freely utilized by the caller of this function. Any data pointed to by the priv pointer is available to the recipient of the dmx_section_cb() function call.

While the maximum section filter length (DMX_MAX_FILTER_SIZE) is currently set at 16 bytes, hardware filters of that size are not available on all platforms. Therefore, section filtering will often take place first in hardware, followed by filtering in software for the header bytes that were not covered by a hardware filter. The filter_mask field can be checked to determine how many bytes of the section filter are actually used, and if the hardware filter will suffice. Additionally, software-only section filters can optionally be allocated to clients when all hardware section filters are in use. Note that on most demux hardware it is not possible to filter on the section_length field of the section header – thus this field is ignored, even though it is included in filter_value and filter_mask fields.

int allocate_filter(dmx_section_feed_t⋆ feed, dmx_section_filter_t⋆⋆ filter);

dmx_section_feed_t* feed

Pointer to the section feed API and instance data.

dmx_section_filter_t** filter

Pointer to the allocated filter.

0

The function was completed without errors.

-ENOSPC

No filters of given type and length available.

-EINVAL

Bad parameters.