Samsung Electronics logo

Samsung Web API: Power

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides support for requesting power management related resource states.

For more information on the Power features, see Power Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
PowerManagerObject
PowerManager void request(PowerResource resource, PowerState state)
void release(PowerResource resource)
void setScreenStateChangeListener(ScreenStateChangeCallback listener)
void unsetScreenStateChangeListener()
double getScreenBrightness()
void setScreenBrightness(double brightness)
boolean isScreenOn()
void restoreScreenBrightness()
void turnScreenOn()
void turnScreenOff()
ScreenStateChangeCallback void onchanged(PowerScreenState previousState, PowerScreenState changedState)

1. Type Definitions

1.1. PowerResource

An enumerator that defines power resources with values aligned with SystemInfo property values. 

    enum PowerResource    { "SCREEN", "CPU" };

We support screen and cpu resources for now. Supported power resource states are provided in PowerScreenState and PowerCpuState enums respectively prefixed by the corresponding resource type.

1.2. PowerScreenState

An enumerator that indicates the power state for screen resource. 

    enum PowerScreenState { "SCREEN_OFF", "SCREEN_DIM", "SCREEN_NORMAL", "SCREEN_BRIGHT" };

The supported values are:

  • SCREEN_OFF - This screen state cannot be requested but can only be used in the state change callback.
  • SCREEN_DIM - The minimal screen state is set to DIM and device does not change to OFF state automatically.
  • SCREEN_NORMAL - The minimal screen state is set to NORMAL and device does not change to DIM state automatically.
  • SCREEN_BRIGHT (Deprecated) - The minimal screen state is set to BRIGHT and device does not change to NORMAL state automatically.

DIM state refers to the screen that the backlight is turned off NORMAL state refers to the default screen brightness that a user has configured for the device. BRIGHT(Deprecated) state refers to the maximum screen brightness that the device provides. Note that the change in brightness does not affect the system brightness setting, i.e., the system brightness value is automatically restored when the resource is released or the process is completed.

1.3. PowerCpuState

An enumerator that indicates the power state for cpu resource. 

    enum PowerCpuState { "CPU_AWAKE" };

The supported values are:

  • CPU_AWAKE - The cpu state is set to be awaken and it does not go to SLEEP state automatically.

1.4. PowerState

The supported power states in general. It can be either a PowerScreenState or a PowerCpuState. 

    typedef (PowerScreenState or PowerCpuState) PowerState;

2. Interfaces

2.1. PowerManagerObject

This interface defines what is instantiated by the webapis object. 

    [NoInterfaceObject] interface PowerManagerObject {
        readonly attribute PowerManager power;
    };
    WebAPIs implements PowerManagerObject;

There will be a webapis.powerobject that allows accessing of a functionality of the Power API.

2.2. PowerManager

This interface is used to request resource states, however, these requests can be overridden by the system. If the requests are overridden, the application is notified with the provided listener callback. 

   [NoInterfaceObject] interface PowerManager {
       void request(PowerResource resource, PowerState state) raises(WebAPIException);

       void release(PowerResource resource) raises(WebAPIException);

       void setScreenStateChangeListener(ScreenStateChangeCallback listener) raises(WebAPIException);

       void unsetScreenStateChangeListener() raises(WebAPIException);

       double getScreenBrightness() raises(WebAPIException);

       void setScreenBrightness(double brightness) raises(WebAPIException);

       boolean isScreenOn() raises(WebAPIException);

       void restoreScreenBrightness() raises(WebAPIException);

       void turnScreenOn() raises(WebAPIException);

       void turnScreenOff() raises(WebAPIException);
   };

METHODS

request

Requests the minimum-state for a power resource.

Signature
void request(PowerResource resource, PowerState state);
Parameters
  • resource
    • Optional: No.
    • Nullable: No.
    • Type: PowerResource.
    • Description: The power resource for which the request is made.
  • state
    • Optional: No.
    • Nullable: No.
    • Type: PowerState.
    • Description: The minimal power state in which the power resource is desired to be.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 webapis.power.request("SCREEN", "SCREEN_NORMAL");

release

Releases the power state request for the given resource.

Signature
void release(PowerResource resource);
Parameters
  • resource
    • Optional: No.
    • Nullable: No.
    • Type: PowerResource.
    • Description: The resource for which requests are to be removed.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Release SCREEN resource.
 webapis.power.release("SCREEN");

setScreenStateChangeListener

Sets the screen state change callback and monitors its state changes.

Signature
void setScreenStateChangeListener(ScreenStateChangeCallback listener);
Parameters
  • listener
    • Optional: No.
    • Nullable: No.
    • Type: ScreenStateChangeCallback.
    • Description: The screen state change callback.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 function onScreenStateChanged(previousState, changedState) {
   console.log("Screen state changed from " + previousState + " to " + changedState);
 }

 // Set the screen state change listener.
 webapis.power.setScreenStateChangeListener(onScreenStateChanged);

unsetScreenStateChangeListener

Unsets the screen state change callback and stop monitoring it.

Signature
void unsetScreenStateChangeListener();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 // Unset the screen state change listener.
 webapis.power.unsetScreenStateChangeListener();

getScreenBrightness

Gets the screen brightness level of an application, from 0 to 1.

Signature
double getScreenBrightness();
Return value
double Current screen brightness value.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 // Get the current screen brightness value.
 var screenBrightness = webapis.power.getScreenBrightness();

setScreenBrightness

Sets the screen brightness level for an application, from 0 to 1.

Signature
void setScreenBrightness(double brightness);
Parameters
  • brightness
    • Optional: No.
    • Nullable: No.
    • Type: double.
    • Description: The screen brightness value to set.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    with error type NotSupportedError, if this feature is not supported.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

Code example
 // Set the screen brightness value for the application.
 webapis.power.setScreenBrightness(1);

isScreenOn

Returns true if the screen is on.

Signature
boolean isScreenOn();
Return value
boolean true if screen is on.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 // Check whether the screen is on or off.
 var isScreenOn = webapis.power.isScreenOn();

restoreScreenBrightness

Restores the screen brightness to the system default setting value.

Signature
void restoreScreenBrightness();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

Code example
 // Restore the screen brightness value to the system default setting value.
 webapis.power.restoreScreenBrightness();

turnScreenOn

Turns on the screen.

Signature
void turnScreenOn();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

Code example
 // Turn on the screen.
 webapis.power.turnScreenOn();

turnScreenOff

Turns off the screen.

Signature
void turnScreenOff();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if this feature is not supported.

Code example
 // Turn off the screen.
 webapis.power.turnScreenOff();

2.3. ScreenStateChangeCallback

This callback interface defines notification for the screen state changes. 

   [Callback=FunctionOnly, NoInterfaceObject] interface ScreenStateChangeCallback {
       void onchanged(PowerScreenState previousState, PowerScreenState changedState);
   };

METHODS

onchanged

Called on screen state change.

Signature
void onchanged(PowerScreenState previousState, PowerScreenState changedState);
Parameters
  • previousState
    • Optional: No.
    • Nullable: No.
    • Type: PowerScreenState.
    • Description: The previous screen state.
  • changedState
    • Optional: No.
    • Nullable: No.
    • Type: PowerScreenState.
    • Description: The changed screen state.

3. Full WebIDL 

module Power {

    enum PowerResource    { "SCREEN", "CPU" };

    enum PowerScreenState { "SCREEN_OFF", "SCREEN_DIM", "SCREEN_NORMAL", "SCREEN_BRIGHT" };

    enum PowerCpuState { "CPU_AWAKE" };

    typedef (PowerScreenState or PowerCpuState) PowerState;

    [NoInterfaceObject] interface PowerManagerObject {
        readonly attribute PowerManager power;
    };
    WebAPIs implements PowerManagerObject;

   [NoInterfaceObject] interface PowerManager {
       void request(PowerResource resource, PowerState state) raises(WebAPIException);

       void release(PowerResource resource) raises(WebAPIException);

       void setScreenStateChangeListener(ScreenStateChangeCallback listener) raises(WebAPIException);

       void unsetScreenStateChangeListener() raises(WebAPIException);

       double getScreenBrightness() raises(WebAPIException);

       void setScreenBrightness(double brightness) raises(WebAPIException);

       boolean isScreenOn() raises(WebAPIException);

       void restoreScreenBrightness() raises(WebAPIException);

       void turnScreenOn() raises(WebAPIException);

       void turnScreenOff() raises(WebAPIException);
   };

   [Callback=FunctionOnly, NoInterfaceObject] interface ScreenStateChangeCallback {
       void onchanged(PowerScreenState previousState, PowerScreenState changedState);
   };

};