org.ocap.hardware.device.HostSettings Maven / Gradle / Ivy
package org.ocap.hardware.device;
import org.havi.ui.HScreen;
import org.ocap.hardware.Host;
import org.ocap.hardware.PowerModeChangeListener;
import org.ocap.hardware.VideoOutputPort;
/**
* System-level extensions to OCAP Host.
* On Host devices implementing this specification, the instance of Host
* returned by {@link Host#getInstance} SHALL also implement this interface.
*/
public interface HostSettings
{
/**
* Constant representing a narrow range of volume control.
*/
public static final int RANGE_NARROW = 1;
/**
* Constant representing a normal range of volume control.
*/
public static final int RANGE_NORMAL = 2;
/**
* Constant representing a wide range of volume control.
*/
public static final int RANGE_WIDE = 3;
/**
* Transition the power mode of the system to the given mode.
*
*
* If the power mode is already in the target mode, this method
* SHALL do nothing.
*
* Setting host power mode to low-power SHALL not disrupt
* any ongoing recording.
*
* In devices where a separate power mode is maintained for standby
* recordings, setting the power mode to low-power SHALL transition
* to standby-recording power mode when a recording is in progress.
*
*
* A change of power mode SHALL be communicated to installed
* {@link PowerModeChangeListener}s.
*
* The power mode set via this method SHALL NOT be persisted and
* restored at boot time (see {@link #resetAllDefaults}). The default
* power mode at boot time is specified by the OCAP specification.
*
* @param mode The new power mode for the system.
*
* @throws IllegalArgumentException if mode is not one of
* {@link Host#FULL_POWER} or {@link Host#LOW_POWER}
* @throws SecurityException if the caller does not have
* MonitorAppPermission("powerMode? or "deviceController")
*/
public void setPowerMode( int mode );
/**
* Get the set of individually controllable audio outputs for this host.
*
* @return The set of AudioOutputPorts as an Enumeration.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("deviceController")
*/
public java.util.Enumeration getAudioOutputs();
/**
* Enable or disable system handling of volume keys.
*
* This method may be used by applications to disable the OCAP default
* behavior of system volume level being handled by the OCAP device
* based upon volume keys (i.e., VK_VOLUME_UP and VK_VOLUME_DOWN).
* OCAP-defined behavior SHALL be the default if this method is never called.
*
* If the system volume control is disabled, the device SHALL not process
* volume key events internally. In other words, the volume keys SHALL
* no longer be considered system keys when system volume control
* is disabled. While disabled it is the responsibility of applications
* to manage the master volume of the device via the {@link AudioOutputPort}
* API.
*
* @param enable Enable or disable system handling of volume keys.
* If true is specified, then system volume SHALL
* be handled by the OCAP device (as is the default).
* If false is specified, then the system volume
* SHALL NOT be managed directly by the OCAP device based
* upon volume keys.
*
* @throws SecurityException If the caller does not have
* MonitorAppPermission("deviceController")
*/
public void setSystemVolumeKeyControl(boolean enable);
/**
* Enable or disable system handling of the mute key.
*
* This method may be used by applications to disable the OCAP default
* behavior of system volume muting being handled by the OCAP device
* based upon the mute key (i.e., VK_MUTE).
* OCAP-defined behavior SHALL be the default if this method is never called.
*
* If the system volume mute control is disabled, the device SHALL not process
* the volume mute events internally. In other words, the mute key SHALL
* no longer be considered a system key when system volume mute control
* is disabled. While disabled it is the responsibility of applications
* to manage the master volume mute state of the device via the {@link AudioOutputPort}
* API.
*
* @param enable Enable or disable system handling of the volume mute key.
* If true is specified, then system volume mute SHALL
* be handled by the OCAP device (as is the default).
* If false is specified, then the system volume mute
* SHALL NOT be managed directly by the OCAP device based
* upon the mute key.
*
* @throws SecurityException If the caller does not have
* MonitorAppPermission("deviceController")
*/
public void setSystemMuteKeyControl(boolean enable);
/**
* Set the range of volume level controlled by the system volume keys.
*
* This method may be used by applications to control the range in dB levels
* controlled by the system volume keys.
* If system volume control is disabled (via {@link #setSystemVolumeKeyControl})
* then this setting SHALL have no effect.
*
* The following table describes the range values.
*
* Range Description RANGE_NARROWA very limited range of volume level is controllable via system volume keys.
* RANGE_NORMALA limited range of volume level is controllable via system volume keys.
* RANGE_WIDEThe full volume level is controllable via system volume keys.
*
*
* @param range The desired control range.
* One of {@link #RANGE_NARROW}, {@link #RANGE_NORMAL}, or {@link #RANGE_WIDE}
*
* @throws IllegalArgumentException if an invalid range value is specified
* @throws SecurityException if the caller does not have
* MonitorAppPermission("deviceController")
*/
public void setSystemVolumeRange(int range);
/**
* Get the main video output port for the given HScreen.
*
* @return The instance of VideoOutputPort that represents the
* main video output port for the given screen
*/
public VideoOutputPort getMainVideoOutputPort(HScreen screen);
/**
* Set the main video output port for the given HScreen.
*
* Changing this setting MAY affect the configuration of HScreenDevices
* of the given HScreen to maintain consistent display
* aspect ratios as described in the body of this specification.
*
* @param screen The specified HScreen for which to set the main
* video output port.
* @param port The desired main VideoOutputPort.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("deviceController")
* @throws FeatureNotSupportedException if the given setting is not supported
*/
public void setMainVideoOutputPort(HScreen screen, VideoOutputPort port) throws FeatureNotSupportedException;
/**
* Reset all Host device settings to their factory default values.
*
* Calling this method SHALL result in the Host restoring all configurable
* scalar settings to their default values, regardless of storage location.
* This includes both settings that persist and do no persist across Host
* device reboots.
*
* This method SHALL affect the following:
*
* - All settings defined by this specification.
* Including {@link AudioOutputPort audio} and {@link VideoOutputSettings video}
* as well as those defined by this class.
*
- All {@link Host} settings.
* Including {@link Host#setRFBypass RF bypass} and {@link Host#setACOutlet AC outlet} settings.
*
- Closed-captioning settings controllable via
* the {@link org.ocap.media.ClosedCaptioningAttribute ClosedCaptioningAttribute}.
*
- User preferences controllable via the
* {@link org.dvb.user.UserPreferenceManager UserPreferenceManager}.
*
* Further, any subsequent operations that would be affected by this change
* in settings SHALL be affected as if the corresponding API were invoked
* directly.
*
* @throws SecurityException if the caller does not have
* MonitorAppPermission("deviceController")
*/
public void resetAllDefaults();
}