From 4291db6846900511fc5daa498b827158f777bfd9 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Mon, 13 Sep 2021 16:43:57 +0200 Subject: [PATCH] editorial: Modernize and replace prose with algorithms in BatteryManager (#46) * editorial: Modernize and replace prose with algorithms in BatteryManager Similarly to #45, make the `BatteryManager` section more conformant to modern spec writing practices, while avoiding making user-visible changes as much as possible: - Define a task source for this spec, and switch from "queue a task" to the more specific and recent "queue a global task" algorithm. - Replace a lot of prose with internal slots and algorithms. - Make the interface attributes simply return the values of the internal slots rather than defining logic in their getters. - Define an actual algorithm for updating internal slots and dispatching events. The existing prose just said "the UA must change the attribute and fire an event" without really defining how to reach a `BatteryManager` object in the first place. * Use [= =] notation in the update battery status and notify algorithm. * Remove non-normative description of BatteryManager's internal slots. The contents are essentially the same as the normative descriptions in the subsequent section. * Use {{BatteryManager}} to refer to it in the text. Refer to the Web IDL interface rather than the BatteryManager concept. * BatteryManager: Define and reference the event types in the Event Handler table. --- index.html | 387 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 259 insertions(+), 128 deletions(-) diff --git a/index.html b/index.html index dfa5010..bd78e27 100644 --- a/index.html +++ b/index.html @@ -114,15 +114,6 @@

it contains.

-
-

- Terminology -

-

- The following term is defined in [[!DOM]]: fires an event. -

-

Security and privacy considerations @@ -151,6 +142,15 @@

is exposing fake values.

+
+

+ Concepts +

+

+ The task source for the tasks mentioned in this + specification is the battery status task source. +

+

Extensions to the `Navigator` interface @@ -203,7 +203,7 @@

`null` - The BatteryManager instance associated with a given + The {{BatteryManager}} instance associated with a given {{Navigator}} after it has been created via {{Navigator/getBattery()}}. @@ -240,8 +240,8 @@

  • Otherwise:
    1. If [=this=].{{Navigator/[[BatteryManager]]}} is `null`, then - set it to the result of [=creating a new `BatteryManager` - object=] in [=this=].[=relevant realm=]. + set it to the result of creating a [=new=] {{BatteryManager}} in + [=this=]'s [=relevant realm=].
    2. [=Resolve=] [=this=].{{Navigator/[[BatteryPromise]]}} with [=this=].{{Navigator/[[BatteryManager]]}}. @@ -253,24 +253,10 @@

    • -
    +

    - The BatteryManager interface + The `BatteryManager` interface

    -

    - 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. -

    -
    -

    - Multiple batteries -

    + +
    +

    + Internal slots +

    - 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 `[[Charging]]` internal slot +

    +

    + 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 `[[ChargingTime]]` internal slot +

    +

    + 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 `[[DischargingTime]]` internal slot +

    +

    + 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 `[[Level]]` internal slot +

    +

    + 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 +

    - 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 +

    - 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 +

    - 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 +

    - 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.

    @@ -395,7 +468,7 @@

    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:

    @@ -411,43 +484,101 @@

    - onchargingchange + onchargingchange - chargingchange + `chargingchange`
    - onchargingtimechange + onchargingtimechange - chargingtimechange + `chargingtimechange`
    - ondischargingtimechange + ondischargingtimechange - dischargingtimechange + `dischargingtimechange`
    - onlevelchange + onlevelchange - levelchange + `levelchange`

    +
    +

    + Algorithms +

    +

    + To update the battery status and notify given an internal + slot |slot|, a |value| and an |eventName|, run the following steps: +

    +
      +
    1. Let |global| be the [=current global object=]. +
      2. +
    2. If |global| is not a {{Window}}, abort these steps. +
      3. +
    3. Let |navigator:Navigator| be |global|'s associated {{Navigator}}. +
      4. +
    4. Let |batteryManager:BatteryManager| be the value of |navigator|. + {{Navigator/[[BatteryManager]]}}. +
      5. +
    5. If |batteryManager| is `null`, abort these steps. +
      6. +
    6. [=Queue a global task=] on the [=battery status task source=] + given |global| to run the following steps: +
        +
      1. Set |batteryManager|.|slot| to |value|. +
        2. +
      2. [=Fire an event=] named |eventName| at |batteryManager|. +
        3. +
      +
      7. +
    +
    +
    +

    + Multiple batteries +

    +

    + 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. +

    +