org.ocap.hardware.device
Interface HostSettings


public interface HostSettings

System-level extensions to OCAP Host. On Host devices implementing this specification, the instance of Host returned by Host.getInstance() SHALL also implement this interface.


Field Summary
static int RANGE_NARROW
          Constant representing a narrow range of volume control.
static int RANGE_NORMAL
          Constant representing a normal range of volume control.
static int RANGE_WIDE
          Constant representing a wide range of volume control.
 
Method Summary
 Enumeration getAudioOutputs()
          Get the set of individually controllable audio outputs for this host.
 VideoOutputPort getMainVideoOutputPort(HScreen screen)
          Get the main video output port for the given HScreen.
 void resetAllDefaults()
          Reset all Host device settings to their factory default values.
 void setMainVideoOutputPort(HScreen screen, VideoOutputPort port)
          Set the main video output port for the given HScreen.
 void setPowerMode(int mode)
          Transition the power mode of the system to the given mode.
 void setSystemMuteKeyControl(boolean enable)
          Enable or disable system handling of the mute key.
 void setSystemVolumeKeyControl(boolean enable)
          Enable or disable system handling of volume keys.
 void setSystemVolumeRange(int range)
          Set the range of volume level controlled by the system volume keys.
 

Field Detail

RANGE_NARROW

static final int RANGE_NARROW
Constant representing a narrow range of volume control.

See Also:
Constant Field Values

RANGE_NORMAL

static final int RANGE_NORMAL
Constant representing a normal range of volume control.

See Also:
Constant Field Values

RANGE_WIDE

static final int RANGE_WIDE
Constant representing a wide range of volume control.

See Also:
Constant Field Values
Method Detail

setPowerMode

void setPowerMode(int mode)
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 PowerModeChangeListeners.

Parameters:
mode - The new power mode for the system.
Throws:
IllegalArgumentException - if mode is not one of Host.FULL_POWER or Host.LOW_POWER
SecurityException - if the caller does not have MonitorAppPermission("deviceController")

getAudioOutputs

Enumeration getAudioOutputs()
Get the set of individually controllable audio outputs for this host.

Returns:
The set of AudioOutputPorts as an Enumeration.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("deviceController")

setSystemVolumeKeyControl

void setSystemVolumeKeyControl(boolean enable)
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 AudioOutputPort API.

Parameters:
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")

setSystemMuteKeyControl

void setSystemMuteKeyControl(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 AudioOutputPort API.

Parameters:
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")

setSystemVolumeRange

void setSystemVolumeRange(int range)
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 setSystemVolumeKeyControl(boolean)) then this setting SHALL have no effect. The following table describes the the range values.

Range Description
RANGE_NARROW A very limited range of volume level is controllable via system volume keys.
RANGE_NORMAL A limited range of volume level is controllable via system volume keys.
RANGE_WIDE The full volume level is controllable via system volume keys.

Parameters:
range - The desired control range. One of RANGE_NARROW, RANGE_NORMAL, or RANGE_WIDE
Throws:
IllegalArgumentException - if an invalid range value is specified
SecurityException - if the caller does not have MonitorAppPermission("deviceController")

getMainVideoOutputPort

VideoOutputPort getMainVideoOutputPort(HScreen screen)
Get the main video output port for the given HScreen.

Returns:
The instance of VideoOutputPort that represents the main video output port for the given screen

setMainVideoOutputPort

void setMainVideoOutputPort(HScreen screen,
                            VideoOutputPort port)
                            throws FeatureNotSupportedException
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.

Parameters:
screen - The specified HScreen for which to set the main video output port.
port - The desired main VideoOutputPort.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("deviceController")
FeatureNotSupportedException - if the given setting is not supported

resetAllDefaults

void resetAllDefaults()
                      throws SecurityException
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:

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")