org.ocap.dvr
Interface TimeShiftProperties


public interface TimeShiftProperties

This interface represents a set of time-shift properties that can be set for and queried from a ServiceContext. Any Host device that supports the OpenCable DVR extension SHALL implement this interface by any class that also implements the ServiceContext interface.


Method Summary
 void addTimeShiftListener(TimeShiftListener listener)
          Adds a listener for time-shift events related to this TimeShiftProperties.
 boolean getLastServiceBufferedPreference()
          Gets the "last" service buffered preference.
 long getMaximumDuration()
          Gets the maximum content buffering duration.
 long getMinimumDuration()
          Gets the minimum content buffering duration.
 NetworkInterface getNetworkInterface(boolean presentation)
          Gets the NetworkInterface currently associated with this ServiceContext corresponding to live or time-shifted content.
 boolean getSavePreference()
          Gets the save time-shift contents at service change preference.
 void removeTimeShiftListener(TimeShiftListener listener)
          Removes a previously added listener for time-shift events from this TimeShiftProperties.
 void setLastServiceBufferedPreference(boolean buffer)
          Sets a preference to buffer the last service.
 void setMaximumDuration(long maxDuration)
          Sets the maximum duration of content that MAY be buffered for this ServiceContext.
 void setMinimumDuration(long minDuration)
          Sets the minimum duration of content that SHALL be buffered for this ServiceContext.
 void setPresentation(javax.tv.service.Service service, javax.media.Time time, float rate, boolean action, boolean persistent)
          Sets the JMF media time location from where the playback will begin when a specific service is selected with this service context.
 void setSavePreference(boolean save)
          Sets a preference to retain the time-shift contents for the ServiceContext when a new service is selected.
 

Method Detail

addTimeShiftListener

void addTimeShiftListener(TimeShiftListener listener)
Adds a listener for time-shift events related to this TimeShiftProperties.

Parameters:
listener - The listener to add.
See Also:
removeTimeShiftListener(TimeShiftListener)

removeTimeShiftListener

void removeTimeShiftListener(TimeShiftListener listener)
Removes a previously added listener for time-shift events from this TimeShiftProperties. If the given listener has not previously been added then this method has no effect.

Parameters:
listener - The listener to remove.
See Also:
addTimeShiftListener(TimeShiftListener)

getMinimumDuration

long getMinimumDuration()
Gets the minimum content buffering duration. If this method is called before setMinimumDuration has ever been called, or if content buffering is disabled for this ServiceContext the value returned SHALL be 0.

Returns:
The minimum content buffering duration in seconds.

setMinimumDuration

void setMinimumDuration(long minDuration)
Sets the minimum duration of content that SHALL be buffered for this ServiceContext. Setting the minimum duration to 0 disables time shifting on the ServiceContext.

This method MAY be called at any time regardless of service context state. However, enabling time-shifting or changing the minimum duration SHALL NOT take affect until the ServiceContext is in the not presenting state, presentation pending state, or a new service is selected. If the same service is selected it is implementation dependent regarding whether time-shift enabling takes affect during the selection.

Disabling time shifting by setting the minimum duration to 0 SHOULD take effect immediately.

When enabling of time shifting by changing the minimum duration from zero to a positive value takes effect, a TimeShiftControl SHALL be added to the associated JMF player. When time shifting is disabled by changing the minimum duration to zero any existing TimeShiftControl SHALL be removed from the associated JMF player.

An increase in minimum duration MUST NOT cause any loss of previously buffered content for the current service.

Parameters:
minDuration - Minimum duration in seconds.
Throws:
java.lang.IllegalArgumentException - If the parameter is greater than the current value and Host device does not have enough space to meet the request, or if the parameter is greater than the maximum duration set by the setMaximumDuration method, or if the parameter is less than the duration returned by OcapRecordingManager.getSmallestTimeShiftDuration().
java.lang.SecurityException - if the calling application does not have ServiceContextPermission("*","own") for the ServiceContext object that implements this TimeShiftProperties.

getMaximumDuration

long getMaximumDuration()
Gets the maximum content buffering duration. If this method is called before setMaximumDuration has ever been called, or if content buffering is disabled for this ServiceContext the value returned SHALL be 0.

Returns:
The maximum content buffering duration in seconds.

setMaximumDuration

void setMaximumDuration(long maxDuration)
Sets the maximum duration of content that MAY be buffered for this ServiceContext. Informs the implementation that storing more content than this is not needed by the application owning this ServiceContext.

This method MAY be called at any time regardless of service context state.

Parameters:
maxDuration - Maximum duration in seconds.
Throws:
java.lang.IllegalArgumentException - if the parameter is less than the duration set by the setMinimumDuration method, or if the parameter is less than the duration returned by OcapRecordingManager.getSmallestTimeShiftDuration().
java.lang.SecurityException - if the calling application does not have ServiceContextPermission("*","own") for the ServiceContext object that implements this TimeShiftProperties.

getLastServiceBufferedPreference

boolean getLastServiceBufferedPreference()
Gets the "last" service buffered preference.

Returns:
Preference indication for recording the "last" service. Returns true if "last" service should be buffered, otherwise returns false.

setLastServiceBufferedPreference

void setLastServiceBufferedPreference(boolean buffer)
Sets a preference to buffer the last service. This method has no effect if the size of the time-shift buffer associated with the ServiceContext object implementing this interface is set to zero.

Parameters:
buffer - If true the implementation will buffer the service selected by the ServiceContext object implementing this interface, based on time-shift buffer availability; see the OCAP DVR API specification time-shift buffer requirements. If false the last service will not be buffered.
Throws:
java.lang.SecurityException - if the calling application does not have ServiceContextPermission("*","own") for the ServiceContext object that implements this TimeShiftProperties.

getSavePreference

boolean getSavePreference()
Gets the save time-shift contents at service change preference.

Returns:
True if save time-shift contents at service selection preference is enabled, otherwise returns false.

setSavePreference

void setSavePreference(boolean save)
Sets a preference to retain the time-shift contents for the ServiceContext when a new service is selected. When enabled the time-shift contents are saved back to the value returned by the getMaxTimeShiftDuration method.

Parameters:
save - If true the implementation will retain the time-shift contents for the ServiceContext when a new service is selected. If false the time-shift contents are flushed when a new service is selected.
Throws:
java.lang.IllegalArgumentException - if the parameter is true and the Host device does not have the hardware resources to support the preference.
java.lang.SecurityException - if the calling application does not have ServiceContextPermission("*","own") for the ServiceContext object that implements this TimeShiftProperties.

setPresentation

void setPresentation(javax.tv.service.Service service,
                     javax.media.Time time,
                     float rate,
                     boolean action,
                     boolean persistent)
Sets the JMF media time location from where the playback will begin when a specific service is selected with this service context. Also sets the rate of that playback. If an instance of Time corresponding to value of 0 nanoseconds, or a negative value is set, the playback will begin at the live point. The default values for the time and rate values is live point and normal playback respectively. Calling this method for the same service multiple times sets the values to the most recent call.

The implementation SHALL NOT allow content to be started in the past and beyond the duration set in this ServiceContext, even if content with the time parameter is buffered. In that case presentation SHALL begin at the duration in the past or at the live point as determined by the action parameter.

Parameters:
service - The service to set the media time for.
time - The time the service presentation will start at.
rate - The rate at which to start play back.
action - Indicates what to do when the media time is not buffered when the service is selected. If true presentation starts at the beginning of the buffer, otherwise presentation starts at the live point.
persistent - If true the time and rate apply to every selection of the service, otherwise they will only apply to the selection following a call to this method. In the latter case, once the values are applied to one service selection they are returned to their default values.
Throws:
java.lang.SecurityException - if the calling application does not have ServiceContextPermission("*","own") for the ServiceContext object that implements this TimeShiftProperties.

getNetworkInterface

NetworkInterface getNetworkInterface(boolean presentation)
Gets the NetworkInterface currently associated with this ServiceContext corresponding to live or time-shifted content.

When the NetworkInterface corresponding to live content is requested, this method SHALL return the interface currently reserved by this ServiceContext, if any. This NetworkInterface SHALL be one of the interfaces returned by NetworkInterfaceManager.getNetworkInterfaces(). That is, this SHALL be the same as would be returned by DvbServiceContext.getNetworkInterface() when called by an application executing outside of this service context.

When the NetworkInterface corresponding to time-shifted content is requested, this method SHALL return a reference to a "special" NetworkInterface as defined in the main body of the specification for DvbServiceContext.getNetworkInterface(). That is, this SHALL be the same as would be returned by DvbServiceContext.getNetworkInterface when called by an application executing within this service context.

Parameters:
presentation - false indicates that the NetworkInterface corresponding to live content is to be returned; true indicates that the NetworkInterface corresponding to time-shifted content is to be returned.
Returns:
the specified NetworkInterface or null