WebAPI/PowerManagementAPI

API

partial interface Navigator {
  readonly attribute PowerManager power;
};

interface PowerManager {
  /**
   * This API will power off the machine.
   */
  void powerOff();

  /**
   * This API will completely shut down and boot the machine.
   */
  void reboot();

  /**
   * This API will restart the Gecko processes without powering off the machine.
   */
  void restart();

  /**
   * The listeners are notified when a resource changes its lock state to:
   *  - unlocked
   *  - locked but not visible
   *  - locked and visible
   */
  void addWakeLockListener(WakeLockListener listener);
  void removeWakeLockListener(WakeLockListener listener);

  /**
   * Query the wake lock state of the topic.
   *
   * Possible states are:
   *
   *  - "unlocked" - nobody holds the wake lock.
   *
   *  - "locked-foreground" - at least one window holds the wake lock,
   *    and it is visible.
   *
   *  - "locked-background" - at least one window holds the wake lock,
   *    but all of them are hidden.
   */
  DOMString getWakeLockState(DOMString topic);

  /**
   * Is the device's screen currently enabled?  This attribute controls the
   * device's screen, so setting it to false will turn off the screen.
   */
  attribute boolean screenEnabled;

  /**
    * Is the device's keypad/button backlight enabled? Setting it to false will
    * turn off the device's keypad/button backlight. And the brightness level
    * is the same as |screenBrightness|.
    */
  attribute boolean keyLightEnabled;

  /**
   * How bright is the screen's backlight, on a scale from 0 (very dim) to 1
   * (full brightness)?  Setting this attribute modifies the screen's
   * brightness.
   *
   * You can read and write this attribute even when the screen is disabled,
   * but the backlight is off while the screen is disabled.
   *
   * If you write a value of X into this attribute, the attribute may not have
   * the same value X when you later read it.  Most screens don't support as
   * many different brightness levels as there are doubles between 0 and 1, so
   * we may reduce the value's precision before storing it.
   *
   * @throw NS_ERROR_INVALID_ARG if brightness is not in the range [0, 1].
   */
  attribute double screenBrightness;

  /**
   * Is it possible that the device's CPU will sleep after the screen is
   * disabled?  Setting this attribute to false will prevent the device
   * entering suspend state.
   */
  attribute boolean cpuSleepAllowed;
};

interface WakeLockListener {
 /**
  * The callback will be called when a lock topic changes its lock
  * state.
  *
  * Possible states are:
  *
  *  - "unlocked" - nobody holds the wake lock.
  *
  *  - "locked-foreground" - at least one window holds the wake lock,
  *    and it is visible.
  *
  *  - "locked-background" - at least one window holds the wake lock,
  *    but all of them are hidden.
  *
  * @param topic The resource name related to the wake lock.
  * @param state The wake lock state
  */
 void callback(DOMString topic, DOMString state);
};

Security/Privacy implications

Only privileged code could access PowerManager.

ToDo

PowerManager probably should implement the EventTarget interface and remove the add/remove wake lock listener method.