com.oracle.deviceaccess.power

Interface PowerSavingHandler

public interface PowerSavingHandler

The PowerSavingHandler interface defines methods for getting notified of power state change requests on a specific Peripheral instance.
A PowerSavingHandler can be registered using the PowerManaged.enablePowerSaving(int, com.oracle.deviceaccess.power.PowerSavingHandler) method.

A power saving handler should implement the following requirements:

• it should be implemented to be as fast as possible; for example it should not call any operations that may block, nor pause the current thread.
• it should not throw any unchecked exception.

A compliant implementation of this specification MUST catch unchecked exceptions that may be thrown by a power saving handler and MAY guard against a hanging handler by timing out in order to guarantee the notification of all the registered power saving handlers.

See Also:

PowerManaged

Method Summary

Methods

Modifier and Type	Method and Description
<P extends Peripheral<? super P>> void	handlePowerStateChange(P peripheral, PowerManaged.Group group, int currentState, int requestedState, long duration) Invoked to allow the application to handle a power state change on the designated Peripheral instance or PowerManaged.Group instance.
<P extends Peripheral<? super P>> long	handlePowerStateChangeRequest(P peripheral, PowerManaged.Group group, int currentState, int requestedState, long duration) Invoked to allow the application to handle a vetoable power state change request on the designated Peripheral instance or PowerManaged.Group instance.

Method Detail

handlePowerStateChangeRequest

<P extends Peripheral<? super P>> long handlePowerStateChangeRequest(P peripheral,
                                                                   PowerManaged.Group group,
                                                                   int currentState,
                                                                   int requestedState,
                                                                   long duration)

Invoked to allow the application to handle a vetoable power state change request on the designated Peripheral instance or PowerManaged.Group instance. The application may veto the power state change by returning 0. Otherwise it should return a duration lesser or equal to the proposed state change duration. An application may veto altogether a power state change from PowerManaged.POWER_ON to PowerManaged.LOWEST_POWER if for example the application is currently using or is about to use the designated peripheral. An application may grant a power state change duration lesser than the specified duration if for example the application anticipates it will use the designated peripheral earlier than the specified duration.

Since a transition to the PowerManaged.POWER_ON state can never be vetoed such as to not deny peripheral access to other applications this method is never invoked prior to a transition to the PowerManaged.POWER_ON state.

Once all the PowerSavingHandlers registered for the peripheral have been called the handlePowerStateChange(com.oracle.deviceaccess.Peripheral, PowerManaged.Group, int, int, long) is invoked with the smallest of the negotiated durations unless the power state change has been vetoed.

Parameters:

peripheral - the Peripheral instance for which a power state change is requested or null if this PowerSavingHandler is registered for group notifications.

group - the PowerManaged.Group instance that contains the Peripheral instance for which a power state change is requested (never null).

currentState - the current power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

requestedState - the requested power state: PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

duration - the expected duration (in milliseconds) of the new requested state; PowerManaged.UNLIMITED_DURATION if unlimited or unknown.

Returns:

a duration (in milliseconds) lesser or equal to duration or 0 if the power state change is vetoed or PowerManaged.UNLIMITED_DURATION if unlimited or unknown.

handlePowerStateChange

<P extends Peripheral<? super P>> void handlePowerStateChange(P peripheral,
                                                            PowerManaged.Group group,
                                                            int currentState,
                                                            int requestedState,
                                                            long duration)

Invoked to allow the application to handle a power state change on the designated Peripheral instance or PowerManaged.Group instance. This method is invoked under two circumstances:

• once the handlePowerStateChangeRequest(P, com.oracle.deviceaccess.power.PowerManaged.Group, int, int, long) method of all the PowerSavingHandlers registered for the peripheral has been called without veto
• upon an urgent (non-vetoable) power state change requested by the power management facility.

Parameters:

peripheral - the Peripheral instance for which a power state change is requested or null if this PowerSavingHandler is registered for group notifications.

group - the PowerManaged.Group instance that contains the Peripheral instance for which a power state change is requested (never null).

currentState - the current power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

requestedState - the requested power state: PowerManaged.POWER_ON, PowerManaged.LOW_POWER, PowerManaged.LOWEST_POWER or PowerManaged.POWER_OFF.

duration - the duration (in milliseconds) of the new requested state; PowerManaged.UNLIMITED_DURATION if unlimited or unknown.