org.ocap.media
Interface VBIFilter


public interface VBIFilter

This class represents a VBI filter. VBIFilter instances are created by a VBIFilterGroup based on the OCAP resource management. Line numbers and a data format to be filtered are specified when the filter is created.

The startFiltering() method starts filtering of the specified data format in the specified VBI line and stores data units in an internal buffer. When the first single data unit is filtered, a VBIFilterEvent with EVENT_CODE_FIRST_VBI_DATA_AVAILABLE is issued only once. The VBIFilter continues filtering.

VBI filtering stops in the following cases:

VBI filtering continues in the following cases:

See also the VBIFilterGroup.


Method Summary
 void addVBIFilterListener(VBIFilterListener listener)
          Add a new VBIFilterListener instance to this VBI filter.
 void clearBuffer()
          Clear an internal buffer to store retrieved VBI data.
 byte[] getVBIData()
          This method returns multiple VBI data unit bytes.
 void removeVBIFilterListener(VBIFilterListener listener)
          Remove an existing VBIFilterListener instance from this VBI filter.
 void setNotificationByDataUnits(int numberOfDataUnits)
          Set the number of data units to receive a cyclic notification.
 void setNotificationByTime(long milliseconds)
          Set a notification time.
 void setTimeOut(long milliseconds)
          Set a timeout value.
 void startFiltering(java.lang.Object appData)
          Initiate filtering of VBI data for the specified line and the specified data format by a VBIFilterGroup.
 void startFiltering(java.lang.Object appData, int offset, byte[] posFilterDef, byte[] posFilterMask, byte[] negFilterDef, byte[] negFilterMask)
          Initiate filtering of VBI data for the specified line and the specified data format by a VBIFilterGroup.
 void stopFiltering()
          Stop current filtering of this VBI filter.
 

Method Detail

startFiltering

void startFiltering(java.lang.Object appData)
Initiate filtering of VBI data for the specified line and the specified data format by a VBIFilterGroup. Filtering starts only after the VBIFilterGroup.attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method is called.

Parameters:
appData - application specific data. This data is notified to the application with a SectionFilterEvent. Null is possible.

startFiltering

void startFiltering(java.lang.Object appData,
                    int offset,
                    byte[] posFilterDef,
                    byte[] posFilterMask,
                    byte[] negFilterDef,
                    byte[] negFilterMask)
Initiate filtering of VBI data for the specified line and the specified data format by a VBIFilterGroup. Only data unit(s) matching with a specified filter parameters are retrieved. Filtering starts only after the VBIFilterGroup.attach(javax.tv.service.selection.ServiceContext, org.davic.resources.ResourceClient, java.lang.Object) method is called.

Parameters:
appData - application specific data. This data is notified to the application with a SectionFilterEvent. Null is possible.
offset - defines a number of offset bytes that the specified matching bits and masking bits are applied. Value 0 means no offset. Value 1 means that the matching/masking bit is applied from the second byte.
posFilterDef - defines values to match for bits in a single data unit. Only data unit that has matching bytes with this posFilterDef are retrieved. Maximum length is 36 bytes.
posFilterMask - defines which bits in the data unit are to be compared against the posFilterDef bytes. Matching calculation of negFilterDef and negFilterMask obeys E.8.1 of DAVIC 1.4.1 Part 9. Maximum length is 36 bytes.
negFilterDef - defines values to match for bits in a single data unit. Only data unit that has matching bytes with this negFilterDef are retrieved. Maximum length is 36 bytes.
negFilterMask - defines which bits in the data unit are to be compared against the negFilterDef bytes. Matching calculation of negFilterDef and negFilterMask obeys E.8.1 of DAVIC 1.4.1 Part 9. Maximum length is 36 bytes.

stopFiltering

void stopFiltering()
Stop current filtering of this VBI filter. Note that the VBIFilterGroup holding this VBI filter doesn't detach.


setTimeOut

void setTimeOut(long milliseconds)
Set a timeout value. If no VBI data unit is retrieved after calling the startFiltering() method within the timeout value, the filtering stops automatically and SectionFilterEvent with EVENT_CODE_TIMEOUT notifies a timeout occurred.

Parameters:
milliseconds - a timeout value in milli seconds. A default value is -1 that indicates infinite.

setNotificationByTime

void setNotificationByTime(long milliseconds)
Set a notification time. By setting a notification time, the OCAP implementation notifies a VBIFilterEvent with EVENT_CODE_TIME_NOTIFICATION when the specified time-period has elapsed after receiving the first byte of the data unit. The event shall be sent even if the data received does not form a complete data unit. The event is sent only once. The filter continues filtering after sending the event.

Parameters:
milliseconds - a time-period value in milli seconds. A default value is -1 that indicates infinite.

setNotificationByDataUnits

void setNotificationByDataUnits(int numberOfDataUnits)
Set the number of data units to receive a cyclic notification. By setting the number of data units, the OCAP implementation notifies a VBIFilterEvent with EVENT_CODE_UNITS_NOTIFICATION cyclically every time when the specified number of new data units are filtered and stored in a buffer. The filter continues filtering after sending the event.

Parameters:
numberOfDataUnits - the number of data units to be notified. A default value is 0 that indicates no notification. Note that if a small number of data units is specified, the notification may be delayed and affect the host performance. For example, if 1 is specified for UNKNOWN data unit that comes every field (i.e., 1/60 seconds), the host has to notify every 1/60 seconds and makes an over load.
Throws:
java.lang.IllegalArgumentException - if the numberOfDataUnit is larger than the bufferSize specified by a VBIFilterGroup.newVBIFilter(int[], int, int, int, int) method.

addVBIFilterListener

void addVBIFilterListener(VBIFilterListener listener)
Add a new VBIFilterListener instance to this VBI filter. If the same instance that exists currently is specified, this method does nothing and no exception is thrown.

Parameters:
listener - a VBIFilterListener instance to be notified a VBI filtering events.

removeVBIFilterListener

void removeVBIFilterListener(VBIFilterListener listener)
Remove an existing VBIFilterListener instance from this VBI filter. If the specified instance has not been added, this method does nothing and no exception is thrown.


getVBIData

byte[] getVBIData()
This method returns multiple VBI data unit bytes. The data unit format is defined in a description of a VBIFilter interface. The returned bytes is a simple concatenated VBI data at the moment. Note that the return value is not aligned by a complete VBI data unit, i.e., an incomplete data unit may return. When this method is called, the internal buffer is cleared once, i.e., the next call returns the next byte of retrieved VBI data.

Returns:
a concatenated VBI data of the form of specified by a VBIFilterGroup.newVBIFilter(int[], int, int, int, int) method.

clearBuffer

void clearBuffer()
Clear an internal buffer to store retrieved VBI data. An application shall call this method before the data buffer is full.