com.sun.dtv.filtering
Class DataSectionFilter

java.lang.Object
  com.sun.dtv.filtering.DataSectionFilter

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

CircularFilter, ListFilter, SingleFilter

public class DataSectionFilter
extends Object
implements Cloneable

This class is the root of all filters classes.

Method Summary

void	addSectionFilterListener(FilterEventListener listener) Adds a FilterEventListener to receive events of the DataSectionFilter object.
void	clearGreaterThanFilter() Clears and deactivates any previously set greaterThan filter parameters.
void	clearLessThanFilter() Clears and deactivates any previously set lessThan filter parameters.
void	clearPositiveFilter() Clears and deactivates any previously set positive filter parameters.
void	clearTableId() Clears ant table_id value previously set.
void	clearXorFilter() Clears and deactivates any previously set xor filter parameters.
void	removeSectionFilterListener(FilterEventListener listener) Removes the specified the FilterEventListener which will no longer remove events from the DataSectionFilter.
void	setGreaterThanFilter(int offset, byte[] greaterThanFilterDef, byte[] greaterThanFilterMask) Defines a filter based on specifying of a set of bit positions which, when corresponding values in a data section are concatenated and interpreted as an integer value, will be GREATER THAN the integer generated from the corresponding in the same definition array.
void	setLessThanFilter(int offset, byte[] lessThanFilterDef, byte[] lessThanFilterMask) Defines a filter based on specifying of a set of bit positions which, when corresponding values in a data section are concatenated and interpreted as an integer value, will be LESS THAN the integer generated from the corresponding in the same definition array.
void	setPid(int pid) Sets or changes the value of the PID for use in filtering packets.
void	setPositiveFilter(int offset, byte[] positiveFilterDef, byte[] positiveFilterMask) Defines a filter based on specifying of a set of bit positions which, when corresponding values in section data are concatenated and interpreted as an integer value, will be EQUAL TO the integer generated from the corresponding in the same definition array.
void	setTableId(int table_id) Sets or changes the value of the table_id for use in filtering packets.
void	setTimeOut(long milliseconds) Sets the timeout of the DataSectionFilter.
void	setXorFilter(int offset, byte[] xorData, byte[] xorZeroMask, byte[] xorOneMask) Sets xor data and mask arrays such that bits in the section content specified by the xorZeroMask will evaluate to zero when xor'd with the corresponding xorData bits, and bits specified by the xorOneMask will evaluate to one when xor'd with the corresponding xorData bits.
void	startFiltering(Object refObj) Sets a filter into the "started" state.
void	stopFiltering() Stops filtering of this DataSectionFilter in the parent DataSectionFilterCollection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setPid

public void setPid(int pid)
            throws InvalidFilterException

Sets or changes the value of the PID for use in filtering packets. This method MUST be called at least once before the filter is used

Parameters:

pid - the value of the PID to filter for in incoming sections. Must be a 13 bit field value between 0 and 0x1FFF

Throws:

InvalidFilterException - if the pid is not a valid value between 0 and 0x1FFF

setTableId

public void setTableId(int table_id)
                throws InvalidFilterException

Sets or changes the value of the table_id for use in filtering packets.

Parameters:

table_id - the value of the table_id to filter for in incoming sections Must be an 8 bit field value between 0 and 0xFF

Throws:

InvalidFilterException - if the table_id is not a valid value between 0 and 0xFF

clearTableId

public void clearTableId()
                  throws InvalidFilterException

Clears ant table_id value previously set.

If the filter is attached to a transport stream, the filter will not longer filter on the table_id filter of data sections.

Throws:

InvalidFilterException - A TableSectionFilter must have the table_id field set.

setPositiveFilter

public void setPositiveFilter(int offset,
                              byte[] positiveFilterDef,
                              byte[] positiveFilterMask)
                       throws InvalidFilterException

Defines a filter based on specifying of a set of bit positions which, when corresponding values in section data are concatenated and interpreted as an integer value, will be EQUAL TO the integer generated from the corresponding in the same definition array.

If the associated DataSectionFilterCollection is connected to a TransportStream then filtering will immediately start using these greater than filter parameters.

Parameters:

offset - defines the offset within the section which the first byte of the positiveFilterDef and positiveFilterMask arrays are intended to match. The offset must be greater than or equal to 3 and less than 31

positiveFilterDef - defines an integer value generated by selecting bits according to the supplied mask and concatenating them.

positiveFilterMask - defines which bits in the positiveFilterDef should be selected for the equal to comparison.

Throws:

InvalidFilterException - if the offset is not a valid value, if the arrays are not of the same length, if the offset and array length would cause the filter to extend beyond the native filter's capacity, or if the bit positions selected in the masks have already been selected in a different filter's mask array

clearPositiveFilter

public void clearPositiveFilter()

Clears and deactivates any previously set positive filter parameters.

If the filter is connected to a transport stream, the positive filter parameters will no longer be used to match section data.

setGreaterThanFilter

public void setGreaterThanFilter(int offset,
                                 byte[] greaterThanFilterDef,
                                 byte[] greaterThanFilterMask)
                          throws InvalidFilterException

Defines a filter based on specifying of a set of bit positions which, when corresponding values in a data section are concatenated and interpreted as an integer value, will be GREATER THAN the integer generated from the corresponding in the same definition array.

If the associated DataSectionFilterCollection is connected to a TransportStream then filtering will immediately start using these greater than filter parameters.

Parameters:

offset - defines the offset within the section which the first byte of the greaterThanFilterDef and greaterThanFilterMask arrays are intended to match. The offset must be greater than or equal to 3 and less than 31

greaterThanFilterDef - defines an integer value generated by selecting bits according to the supplied mask and concatenating them.

greaterThanFilterMask - defines which bits in the greaterThanFilterDef should be selected for the greater than comparison.

Throws:

InvalidFilterException - if the offset is not a valid value, if the arrays are not of the same length, if the offset and array length would cause the filter to extend beyond the native filter's capacity, or if the bit positions selected in the mask have already been selected in a different filter's mask array

clearGreaterThanFilter

public void clearGreaterThanFilter()

Clears and deactivates any previously set greaterThan filter parameters.

If the filter is connected to a transport stream, the greaterThan filter parameters will no longer be used to match section data.

setLessThanFilter

public void setLessThanFilter(int offset,
                              byte[] lessThanFilterDef,
                              byte[] lessThanFilterMask)
                       throws InvalidFilterException

Defines a filter based on specifying of a set of bit positions which, when corresponding values in a data section are concatenated and interpreted as an integer value, will be LESS THAN the integer generated from the corresponding in the same definition array.

If the associated DataSectionFilterCollection is connected to a TransportStream then filtering will immediately start using these less than filter parameters.

Parameters:

offset - defines the offset within the section which the first byte of the lessThanFilterDef and lessThanFilterMask arrays are intended to match. The offset must be less than or equal to 3 and less than 31

lessThanFilterDef - defines an integer value generated by selecting bits according to the supplied mask and concatenating them.

lessThanFilterMask - defines which bits in the lessThanFilterDef should be selected for the less than comparison.

Throws:

InvalidFilterException - if the offset is not a valid value, if the arrays are not of the same length, if the offset and array length would cause the filter to extend beyond the native filter's capacity, or if the bit positions selected in the mask have already been selected in a different filter's mask array

clearLessThanFilter

public void clearLessThanFilter()

Clears and deactivates any previously set lessThan filter parameters.

If the filter is connected to a transport stream, the lessThan filter parameters will no longer be used to match section data.

setXorFilter

public void setXorFilter(int offset,
                         byte[] xorData,
                         byte[] xorZeroMask,
                         byte[] xorOneMask)
                  throws InvalidFilterException

Sets xor data and mask arrays such that bits in the section content specified by the xorZeroMask will evaluate to zero when xor'd with the corresponding xorData bits, and bits specified by the xorOneMask will evaluate to one when xor'd with the corresponding xorData bits.

The Mask arrays select bits with a value of 0. Bits in the mask with a value of 1 will not be xor'd and will have no bearing on a section matching the filter.

The following pseudo code illustrates how these logical operations match a section.

 if ((sectionData ^ xorData) & ~xorZeroMask == 0 &&
    ((sectionData ^ xorData) & ~xorOneMask) ^ ~xorOneMask > 0) {
    //SECTION MATCH FOUND
 }
 

Note that to avoid an obvious conflict, the xorZeroMask and xorOneMask contents must not select the same bits for xor checking (as an xor result can not be both one and zero). In effect this enforces the logical requirement, (~xorOneMask) & (~xorOneMask) = 0.

If the associated DataSectionFilterCollection is connected to a TransportStream then filtering will immediately start using these xor filter parameters.

Parameters:

offset - Defines the offset within the section which the first byte of the xorData and xorZeroMask arrays is intended to match. The offset must be greater than or equal to 3 and less than 31.

xorData - Defines values which should resolve to "0" when bits specified by the xorZeroMask are xor'd with the section data, and resolve to "1" when bits specified by the xorOneMask are xor'd with the section data.

xorZeroMask - Defines which bits in the section must resolve to "0" when xor'd with the xorData. A bit with value "0" marks the bit to be xor'd.

xorOneMask - Defines which bits in the section must resolve to "1" when xor'd with the xorData. A bit with value "0" marks the bit to be xor'd.

Throws:

InvalidFilterException - If the arrays are not of the same length, if the xormasks overlap, if the offset is not a valid value, if the offset and array length would cause the filter to extend beyond the native filter's capacity, or if the bit positions selected in the masks have already been selected in a different filter's mask array.

clearXorFilter

public void clearXorFilter()

Clears and deactivates any previously set xor filter parameters.

If the filter is connected to a transport stream, the xor filter parameters will no longer be used to match section data.

startFiltering

public void startFiltering(Object refObj)
                    throws FilterResourceUnavailableException,
                           ConditionalAccessDeniedException,
                           InvalidFilterException,
                           DisconnectedException

Sets a filter into the "started" state. Once the filter is attached to a transport stream through the DataFilterCollection method connect() being called, the filter native resources are allocated and filtering begins with the parameters defined for this filter. If the filter is already part of an attached DataSectionFilterCollection then this filters parameters become active

Parameters:

refObj - An object supplied by the application for use as as an internal reference within the application to uniquely identify the filter operation. If not null, the object will be provided with all DataSectionFilterEvent deliveries.

Throws:

FilterResourceUnavailableException - if all the number of started DataSectionFilters for the containing DataSectionFilterCollection is already equal to the number of section filters reserved for the DataSectionFilterCollection when it was created.

ConditionalAccessDeniedException - if the information requested is scrambled and permission to descramble it is refused.

InvalidFilterException - Insufficient filter parameters have been supplied to permit the filter to start. A ListFilter must have the table_id field set. Also thrown if the offset and length of the xorData, xorZeroMask and xorOneMask arrays cause filtering to extend beyond the native filtering capacity.

DisconnectedException - if the parent DataSectionFilterCollection has lost it's connection to a transport stream since it was connected.

stopFiltering

public void stopFiltering()

Stops filtering of this DataSectionFilter in the parent DataSectionFilterCollection. Connecting the parent DataSectionFilterCollection to a transport stream will not start filtering of this DataSectionFilter.

setTimeOut

public void setTimeOut(long milliseconds)
                throws IllegalArgumentException

Sets the timeout of the DataSectionFilter. A TimeOutEvent will be sent to all FilterEventListener. when the timeout occurs. Filtering will also be stopped.

For a SingleFilter this will be generated if no sections arrive within the specified period. For a ListFilter, this will be generated if the complete table does not arrive within the specified time. For a CircularFilter, this will be generated if the specified time has elapsed since the arrival of the last section being successfully filtered.

Specifying a timeout of 0 removes the timeout resulting in no further TimeOutEvent in subsequent filter activations, but not filter activation already in progress. The default timeout value is 0.

Parameters:

milliseconds - The time out period.

Throws:

IllegalArgumentException - If the 'milliseconds' parameter is negative.

addSectionFilterListener

public void addSectionFilterListener(FilterEventListener listener)

Adds a FilterEventListener to receive events of the DataSectionFilter object.

Parameters:

listener - the FilterEventListener to receive the events.

See Also:

removeSectionFilterListener(com.sun.dtv.filtering.FilterEventListener)

removeSectionFilterListener

public void removeSectionFilterListener(FilterEventListener listener)

Removes the specified the FilterEventListener which will no longer remove events from the DataSectionFilter.

Parameters:

listener - the FilterEventListener to be removed.

See Also:

addSectionFilterListener(com.sun.dtv.filtering.FilterEventListener)