org.ocap.dvr.event
Interface LightweightTriggerSession


public interface LightweightTriggerSession

This interface represents a session created to build an artificial carousel with a DSMCCStreamEvent.


Method Summary
 BufferingRequest getBufferingRequest()
          Gets the BufferingRequest for the stream type of interest.
 OcapLocator getLocator()
          Gets the locator for the artificial carousel.
 NetworkInterface getNetworkInterface()
          Gets the NetworkInterface for the stream type of interest.
 int[] getPIDs()
          Get the array of PIDs for the streams with the stream type of interest.
 RecordingRequest getRecordingRequest()
          Gets the RecordingRequest for the stream type of interest.
 javax.tv.service.Service getService()
          Gets the broadcast service for which this session was created.
 javax.tv.service.selection.ServiceContext getServiceContext()
          Gets the ServiceContext for the stream type of interest.
 short getStreamType()
          Gets the stream type this session was created for and that the handler registered interest in.
 boolean isAuthorized()
          Returns the CA authorization status for the stream(s) referenced by getPIDs().
 boolean isPresenting()
          Returns an indication of service containing stream type is presenting to outputs or display, or if it is being buffered or recorded in the background.
 void registerEvent(java.util.Date date, java.lang.String name, int id, byte[] data)
          Registers a synchronized event to the stream event list for this session.
 void setStreamChangeListener(StreamChangeListener listener)
          Sets the listener for this session.
 void stop()
          Stops the session.
 void store()
          Stores the artificial carousel created for an open session with any permanent recordings made of any elementary streams in the same program as the stream type associated with the open session.
 

Method Detail

getLocator

OcapLocator getLocator()
Gets the locator for the artificial carousel. The locator is only valid during this session. The locator returned is a valid Locator that is implementation specific and unique to the artificial carousel. The locator returned SHALL be valid and usable in a ServiceDomain attach method call as long as the service containing the stream is presenting or is accessible in a time-shift buffer.

The return value is constant for the life of this object.

Returns:
locator Locator of the artificial carousel.

getStreamType

short getStreamType()
Gets the stream type this session was created for and that the handler registered interest in.

The return value is constant for the life of this object.

Returns:
Stream type for this session.

getPIDs

int[] getPIDs()
Get the array of PIDs for the streams with the stream type of interest. The array SHALL be ordered from lowest PID number to highest. Returns the PIDs for the stream type of interest and that are associated with this session.

The return value MAY change over the life of this object. Changes are signaled by invocation of StreamChangeListener.notifyPIDsChanged(int[]) on the set listener.

Returns:
The PIDs for this session.

getService

javax.tv.service.Service getService()
Gets the broadcast service for which this session was created. A reference to a Service object representing the program for which this session was created SHALL be returned.

The return value is constant for the life of this object.

Returns:
a Service object representing the service

getServiceContext

javax.tv.service.selection.ServiceContext getServiceContext()
Gets the ServiceContext for the stream type of interest.

The return value is constant for the life of this object.

Returns:
If a ServiceContext has selected or is in the process of selecting the service containing the stream type of interest and the calling application has permission to access it, then the ServiceContext for this session is returned, otherwise this method returns null.

getBufferingRequest

BufferingRequest getBufferingRequest()
Gets the BufferingRequest for the stream type of interest.

The return value is constant for the life of this object.

Returns:
If the service carrying the stream type of interest is buffering in the background, then the BufferingRequest for the stream is returned, otherwise this method returns null.

getNetworkInterface

NetworkInterface getNetworkInterface()
Gets the NetworkInterface for the stream type of interest.

The return value is constant for the life of this object.

Returns:
If a NetworkInterface is tuned to the service carrying the stream type of interest it is returned, otherwise this method returns null.

getRecordingRequest

RecordingRequest getRecordingRequest()
Gets the RecordingRequest for the stream type of interest.

The return value is constant for the life of this object.

Returns:
If an in-progress or transitioning-to-in-progress recording references the service carrying the stream type of interest, the associated RecordingRequest is returned; otherwise this method returns null.

isPresenting

boolean isPresenting()
Returns an indication of service containing stream type is presenting to outputs or display, or if it is being buffered or recorded in the background.

The return value MAY change over the life of this object. Changes are signaled by invocation of StreamChangeListener.notifyPresentationChanged(boolean) on the set listener.

Returns:
True if the service containing stream type of interest is presenting,otherwise returns false.

isAuthorized

boolean isAuthorized()
Returns the CA authorization status for the stream(s) referenced by getPIDs().

The return value MAY change over the life of this object. Changes are signaled by invocation of StreamChangeListener.notifySessionStopped(int) on the set listener.

Returns:
True if all of the streams are authorized (i.e., can be decrypted); false if otherwise.

registerEvent

void registerEvent(java.util.Date date,
                   java.lang.String name,
                   int id,
                   byte[] data)
Registers a synchronized event to the stream event list for this session.

Parameters:
date - The time when the event is to be generated. The implementation SHALL create JMF media time from this value for use with presenting broadcast and recorded services.
name - A name for the event being registered. This name SHALL appear in the list of events returned by the DSMCCStreamEvent getEventList method.
id - The unique identifier of the event.
data - Application specific data associated with the event. This data will be delivered with the StreamEvent when the media time is incurred in the interested stream during playback. The maximum size of this data is 4096 bytes.
Throws:
java.lang.IllegalArgumentException - if the name or id already exist, or if the data array contains more than 4096 byte entries.
java.lang.IllegalStateException - if the session is not open, i.e. has been stopped by the implementation or an application.

setStreamChangeListener

void setStreamChangeListener(StreamChangeListener listener)
Sets the listener for this session.

If the session has already been stopped by the implementation when the listener is set, then the listener SHALL be notified immediately via StreamChangeListener.notifySessionStopped(int).

Parameters:
listener - The listener to set. If null any previously set listener is removed.

stop

void stop()
Stops the session. If an artificial carousel was created and the store method was called the carousel is stored at this time. If the session was already stopped this method does nothing successfully.


store

void store()
Stores the artificial carousel created for an open session with any permanent recordings made of any elementary streams in the same program as the stream type associated with the open session. The implementation SHALL adjust the media times in the stored DSMCCStreamEvent so that they occur at the same point in the recording presentation as they did in the presentation recorded from. The implementation SHALL store all events added to the DSMCCStreamEvent while the session is active, i.e. events added after the LightweightTriggerHandler.notifyStreamType(org.ocap.dvr.event.LightweightTriggerSession) method was called and before the stop is called for the session. If a session does not contain any registered events that fall within the duration of a recording when the session is stopped the artificial carousel is not stored with the recording. The implementation SHALL update the stored carousel as soon as an event is registered that falls within the duration of the recording. It is illegal to call this method after a session has been closed.

Throws:
java.lang.SecurityException - if the calling application does not have file permission granted in its permission request file.
java.lang.IllegalStateException - if this method is called after the session has been closed, or if there are no events in the artificial carousel.