VBIFilter

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 via `VBIFilterGroup.newVBIFilter(int[], int, int, int, int)`

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:

- If a stopFiltering() method is called, a VBIFilterEvent with EVENT_CODE_FORCIBLE_TERMINATED notifies it.
- If an internal buffer is full, a VBIFilterEvent with EVENT_CODE_BUFFER_FULL notifies it.
- If a time out (specified by a timeout value in a `setTimeOut(long)`) occurs, a VBIFilterEvent with EVENT_CODE_TIMEOUT notifies it.

VBI filtering continues in the following cases:

- Timer notification by a VBIFilterEvent with EVENT_CODE_TIME_NOTIFICATION.
- Cyclic notification for every specified number of data units by a VBIFilterEvent with EVENT_CODE_UNITS_NOTIFICATION.

See also the `VBIFilterGroup`.

Author:
  Shigeaki Watanabe (Panasonic)

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(Object appData)` Initiate filtering of VBI data for the specified line and the specified data format by a VBIFilterGroup.
`void` | `startFiltering(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(Object appData)
                        throws ConnectionLostException

  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 VBIFilterEvent. Null is possible.
  Throws:
    `ConnectionLostException` - if the ServiceContext to which the parent VBIFilterGroup is attached has entered the destroyed state and hence is unable to satisfy the method call, or if the parent VBIFilterGroup has been detached from the ServiceContext.

### startFiltering

    void startFiltering(Object appData,
                        int offset,
                        byte[] posFilterDef,
                        byte[] posFilterMask,
                        byte[] negFilterDef,
                        byte[] negFilterMask)
                        throws ConnectionLostException,
                               IllegalFilterDefinitionException

  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 VBIFilterEvent. 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.
  Throws:
    `ConnectionLostException` - if the ServiceContext to which the parent VBIFilterGroup is attached has entered the destroyed state and hence is unable to satisfy the method call, or if the parent VBIFilterGroup has been detached from the ServiceContext.
    `IllegalFilterDefinitionException` - if the filter definition specified is illegal either because the arrays posFilterDef, posFilterMask, negFilterDef, negFilterMask are not all the same size or because their length is greater than the maximum allowable 36 bytes.

### stopFiltering

    void stopFiltering()

  Stop current filtering of this VBI filter. Note that the VBIFilterGroup holding this VBI filter doesn't detach from the ServiceContext.

### 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 VBIFilterEvent 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 milliseconds. 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 host performance may be affected. For example, if 1 is specified for a VBI_DATA_FORMAT_UNKNOWN data unit that comes every field (i.e., 1/60 seconds), the host has to notify every 1/60 seconds, possibly degrading performance.
  Throws:
    `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 are simply the concatenated VBI data currently held within the internal buffer. Note that the return value is not necessarily 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 should call this method before the data buffer is full.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD