- The following term is defined in [[!DOM]]: fires an event. -
-+ The task source for the tasks mentioned in this + specification is the battery status task source. +
+
- The BatteryManager interface represents the current
- battery status information of the hosting device. The
- charging
- attribute represents the charging state of the system's battery. The
- chargingTime
- attribute represents the time remaining in seconds until the system's
- battery is fully charged. The dischargingTime attribute
- represents the time remaining in seconds until the system's battery is
- completely discharged and the system is about to be suspended, and the
- level attribute
- represents the level of the system's battery.
-
[Exposed=Window]
interface BatteryManager : EventTarget {
@@ -285,107 +271,194 @@
};
- When the user agent is to create a new
- BatteryManager object, it MUST instantiate a new
- BatteryManager object and set its attributes' values to those
- that represent the current battery status information, unless
- the user agent is unable to report the battery status
- information, in which case the values MUST be set to default
- values as follows: charging MUST be set to true,
- chargingTime MUST be set to 0,
- dischargingTime MUST be set to positive Infinity, and
- level MUST be set to 1.0.
+ The BatteryManager interface represents the current
+ battery status information of the hosting device.
The user agent is said to be unable to report the battery - status information, if it is not able to report the values for - any of the attributes, for example, due to a user or system preference, + status information if it is not able to report the values for any + of the attributes, for example, due to a user or system preference, setting, or limitation.
-- Implementations unable to report the battery status information - emulate a fully charged and plugged in battery to reduce the potential - for fingerprinting and prevent applications from degrading performance, - if the battery status information is not made available, for example. -
-
- The charging attribute
- MUST be set to false if the battery is discharging, and set to true, if
- the battery is charging, the implementation is unable to report the
- state, or there is no battery attached to the system, or otherwise.
- When the battery charging state is updated, the user agent MUST
- queue a task which sets the charging attribute's
- value and fires an event named
- chargingchange at the BatteryManager object.
-
- The chargingTime
- attribute MUST be set to 0, if the battery is full or there is no
- battery attached to the system, and to the value positive Infinity if
- the battery is discharging, the implementation is unable to report the
- remaining charging time, or otherwise. When the battery charging time
- is updated, the user agent MUST queue a task which sets
- the chargingTime attribute's value and fires an
- event named chargingtimechange at the
- BatteryManager object.
-
- The dischargingTime attribute
- MUST be set to the value positive Infinity, if the battery is charging,
- the implementation is unable to report the remaining discharging time,
- there is no battery attached to the system, or otherwise. When the
- battery discharging time is updated, the user agent MUST
- queue a task which sets the dischargingTime
- attribute's value and fires an event named
- dischargingtimechange at the BatteryManager
- object.
-
- The level attribute MUST be
- set to 0 if the system's battery is depleted and the system is about to
- be suspended, and to 1.0 if the battery is full, the implementation is
- unable to report the battery's level, or there is no battery attached
- to the system. When the battery level is updated, the user agent
- MUST queue a task which sets the level attribute's
- value and fires an event named levelchange
- at the BatteryManager object.
-
- The definition of how often the chargingtimechange,
- dischargingtimechange, and
- levelchange events are fired is left to the
- implementation.
-
- If a hosting device contains more than one battery, - BatteryManager SHOULD expose an unified view of the batteries. + {{BatteryManager}} instances are created with the following + internal + slots:
+| + Internal slot + | ++ Initial value + | +
|---|---|
| + [[\Charging]] + | ++ `true` + | +
| + [[\ChargingTime]] + | ++ 0 + | +
| + [[\DischargingTime]] + | ++ Positive Infinity + | +
| + [[\Level]] + | ++ 1.0 + | +
+ The {{BatteryManager/[[Charging]]}} internal slot represents the + charging state of the system's battery. It MUST be set to `false` + if the battery is discharging, and set to `true` if the battery is + charging, the implementation is unable to report the state, or + there is no battery attached to the system, or otherwise. +
++ When the system battery's charging state changes, the user agent + must run the update the battery status and notify algorithm + with {{BatteryManager/[[Charging]]}}, `true` or `false` depending + on whether the battery is charging or discharging, and + "[=chargingchange=]". +
++ The {{BatteryManager/[[ChargingTime]]}} internal slot represents + the remaining time in seconds until the system's battery is fully + charged. It MUST be set to 0 if the battery is full or there is no + battery attached to the system, and to the value positive Infinity + if the battery is discharging, the implementation is unable to + report the remaining charging time, or otherwise. +
++ When the battery charging time is updated, the user agent must run + the update the battery status and notify algorithm with + {{BatteryManager/[[ChargingTime]]}}, the new charging time in + seconds, and "[=chargingtimechange=]". +
++ The {{BatteryManager/[[DischargingTime]]}} attribute represents the + remaining time in seconds until the system's battery is completely + discharged and the system is about to be suspended. It MUST be set + to the value positive Infinity if the battery is charging, the + implementation is unable to report the remaining discharging time, + there is no battery attached to the system, or otherwise. +
++ When the battery discharging time is updated, the user agent must + run the update the battery status and notify algorithm with + {{BatteryManager/[[DischargingTime]]}}, the new discharging time in + seconds, and "[=dischargingtimechange=]". +
++ The {{BatteryManager/[[Level]]}} internal slot represents the + system's battery's level. It MUST be set to 0 if the system's + battery is depleted and the system is about to be suspended, and to + 1.0 if the battery is full, the implementation is unable to report + the battery's level, or there is no battery attached to the system. +
++ When the battery level is updated, the user agent must run the + update the battery status and notify algorithm with + {{BatteryManager/[[Level]]}}, the new battery level, and + "[=levelchange=]". +
++ The definition of how often the "[=chargingtimechange=]", + "[=dischargingtimechange=]", and "[=levelchange=]" events are fired + is left to the implementation. +
+
- The charging attribute MUST be set to true if at least
- one battery's charging state as described above is true.
- Otherwise, it MUST be set to false.
+ The charging attribute's getter returns the value of the
+ {{BatteryManager/[[Charging]]}} internal slot.
- The chargingTime attribute can be set to the maximum
- charging time of the individual batteries if charging in parallel,
- and to the sum of the individual charging times if charging serially.
+ The chargingTime attribute's getter returns the value of
+ the {{BatteryManager/[[ChargingTime]]}} internal slot.
- The dischargingTime attribute can be set to the maximum
- discharging time of the individual batteries if discharging in
- parallel, and to the sum of individual discharging times if
- discharging serially.
+ The dischargingTime attribute's getter returns the value
+ of the {{BatteryManager/[[DischargingTime]]}} internal slot.
- The level attribute can be set to the average of the
- levels of batteries of same capacity, or the weighted average of the
- battery level attributes for batteries of different capacities.
+ The level attribute's getter returns the value of the
+ {{BatteryManager/[[Level]]}} internal slot.
The following are the event handlers (and their corresponding event handler event types) that MUST be supported as - attributes by the BatteryManager object: + attributes by the {{BatteryManager}} object:
- onchargingchange
+ onchargingchange
|
- chargingchange
+ `chargingchange`
|
- onchargingtimechange
+ onchargingtimechange
|
- chargingtimechange
+ `chargingtimechange`
|
- ondischargingtimechange
+ ondischargingtimechange
|
- dischargingtimechange
+ `dischargingtimechange`
|
- onlevelchange
+ onlevelchange
|
- levelchange
+ `levelchange`
|
+ To update the battery status and notify given an internal + slot |slot|, a |value| and an |eventName|, run the following steps: +
++ If a hosting device contains more than one battery, + {{BatteryManager}} SHOULD expose a unified view of the batteries. +
++ The {{BatteryManager/[[Charging]]}} internal slot MUST be set to true + if at least one battery's charging state as described above is true. + Otherwise, it MUST be set to false. +
++ The {{BatteryManager/[[ChargingTime]]}} internal slot can be set to + the maximum charging time of the individual batteries if charging in + parallel, and to the sum of the individual charging times if charging + serially. +
++ The {{BatteryManager/[[DischargingTime]]}} internal slot can be set + to the maximum discharging time of the individual batteries if + discharging in parallel, and to the sum of individual discharging + times if discharging serially. +
++ The {{BatteryManager/[[Level]]}} internal slot can be set to the + average of the levels of batteries of same capacity, or the weighted + average of the battery levels for batteries of different capacities. +
+