--- a/battery/Overview.src.html Fri Jun 06 14:47:26 2014 +0300
+++ b/battery/Overview.src.html Fri Jun 06 14:59:06 2014 +0300
@@ -35,7 +35,7 @@
This specification defines an API that provides information about the
battery status of the hosting device.
</section>
-
+
<section id="sotd">
<p>
The functionality described in this specification was initially
@@ -47,7 +47,7 @@
interference with other, often unrelated, features.
</p>
</section>
-
+
<section class="informative">
<h2>Introduction</h2>
<p>
@@ -89,10 +89,10 @@
timer: 0,
check: function () {
- console.log('Checking the server for new emails using an interval of ' +
+ console.log('Checking the server for new emails using an interval of ' +
(mail.interval / 1000) + ' seconds.');
},
-
+
setTimer: function (interval) {
if (interval === mail.interval) { return; }
if (mail.timer !== 0) { clearTimeout(mail.timer); }
@@ -132,12 +132,12 @@
INTERVAL_DEFAULT: 1000 * 10,
interval: null,
timer: 0,
-
+
check: function () {
- console.log('Checking the server for new emails using an interval of ' +
+ console.log('Checking the server for new emails using an interval of ' +
(mail.interval / 1000) + ' seconds.');
},
-
+
setTimer: function (interval) {
if (interval === mail.interval) { return; }
if (mail.timer !== 0) { clearTimeout(mail.timer); }
@@ -145,14 +145,18 @@
mail.interval = interval;
}
};
-
+
window.addEventListener('load', function () {
mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
}, false);
-
- var battery = navigator.battery;
-
- battery.addEventListener('dischargingtimechange', function () {
+
+ function updateTimer(battery) {
+ if (battery.charging) {
+ mail.setTimer(mail.INTERVAL_DEFAULT);
+ console.log('Battery is charging, checking the server normally.');
+ return;
+ }
+
if (battery.dischargingTime < 60 * 30 || battery.level < 0.1) {
mail.setTimer(mail.INTERVAL_BATTERY_LOW);
console.log('30 minutes remaining or level below 10%, checking the server less frequently.');
@@ -160,21 +164,26 @@
mail.setTimer(null);
console.log('10 minutes remaining or level below 5%, stop checking the server.');
}
- }, false);
-
- battery.addEventListener('chargingchange', function () {
- if (battery.charging) {
- mail.setTimer(mail.INTERVAL_DEFAULT);
- console.log('Battery is charging, checking the server normally.');
- }
- }, false);
+ }
+
+ navigator.getBattery().then(function(battery) {
+ battery.addEventListener('levelchange', function() {
+ updateTimer(battery);
+ });
+ battery.addEventListener('dischargingtimechange', function() {
+ updateTimer(battery);
+ });
+ battery.addEventListener('chargingchange', function() {
+ updateTimer(battery);
+ });
+ });
</script>
</head>
<body></body>
</html>
</pre>
</section>
-
+
<section id="conformance">
<p>
This specification defines conformance criteria that apply to a single
@@ -191,26 +200,28 @@
<section>
<h2>Terminology</h2>
<p>
- The <code><a href="http://www.w3.org/html/wg/drafts/html/master/webappapis.html#navigator">
- Navigator</a></code> interface this specification extends is defined
- in [[!HTML5]].
- </p>
- <p>
- The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
- EventHandler</a></code> interface represents a callback used for event
- handlers as defined in [[!HTML5]].
+ The following concepts, terms and interfaces are defined in [[!HTML5]]:
+ <ul>
+ <li><code><a href="http://www.w3.org/html/wg/drafts/html/master/webappapis.html#navigator">
+ Navigator</a></code></li>
+ <li><code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
+ EventHandler</a></code></li>
+ <li><dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn></li>
+ <li><dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn></li>
+ <li><dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ event handlers</a></dfn></li>
+ <li><dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></li>
+ <li><dfn><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
+ browsing context</a></dfn></li>
+ </ul>
</p>
<p>
- The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
- queue a task</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
- fires a simple event</a></dfn> are defined in [[!HTML5]].
- </p>
- <p>
- The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
- event handlers</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
- event handler event types</a></dfn> are defined in [[!HTML5]].
+ <a href=
+ 'http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects'>
+ Promise objects</a> are defined in [[!ECMASCRIPT]].
</p>
</section>
<section class="informative">
@@ -219,21 +230,38 @@
The API defined in this specification is used to determine the battery
status of the hosting device. The information disclosed has minimal
impact on privacy or fingerprinting, and therefore is exposed without
- permission grants. For example, authors cannot directly know if there
- is a battery or not in the hosting device.
+ permission grants. For example, the user agent can obfuscate the
+ exposed value in a way that authors cannot directly know if a hosting
+ device has no battery, is charging or is exposing fake values.
</p>
</section>
<section>
<h2><a>Navigator</a> Interface</h2>
- <p>
- The <code>battery</code> attribute of the <a>Navigator</a> interface
- MUST return an instance of the <a>BatteryManager</a> interface, which
- represents the battery status of the hosting device.
- </p>
<dl title="partial interface Navigator" class="idl">
- <dt>readonly attribute BatteryManager battery</dt>
+ <dt>Promise<BatteryManager> getBattery()</dt>
<dd></dd>
</dl>
+ <p>
+ The <code>getBattery()</code> method, when invoked, MUST run the
+ following steps:
+ <ul>
+ <li>Let <var>promise</var> be a newly created Promise and return it
+ </li>
+ <li>If those steps were previously successfully run in the current
+ <a>browsing context</a>, let <var>battery</var> be the previously
+ returned instance of <a>BatteryManager</a>.</li>
+ <li>Otherwise, let <var>battery</var> be a new instance of
+ <a>BatteryManager</a>.</li>
+ <li>Resolve <var>promise</var> with <var>battery</var>.</li>
+ </ul>
+ </p>
+ <p>
+ The <a>user agent</a> SHOULD NOT reject the promise returned by
+ <code>getBattery()</code>. If the <a>user agent</a> does not want to
+ expose the battery information to the web page, it is RECOMMENDED to
+ not expose <code>getBattery()</code> or resolve the promise with an
+ instance of <a>BatteryManager</a> exposing only default values.
+ </p>
</section>
<section>
@@ -266,12 +294,11 @@
<dd></dd>
</dl>
<p>
- When a <a>BatteryManager</a> object is created,
- <code>charging</code> MUST be set to true, <code>chargingTime</code>
- to 0, <code>level</code> to 1.0 and <code>dischargingTime</code> to
- the value positive Infinity, if the implementation is unable to report
- the battery's charging state, charging time, level or remaining time
- respectively.
+ When a <a>BatteryManager</a> object is created, if the implementation is
+ unable to report the battery's charging state, charging time, level or
+ remaining time, <code>charging</code> MUST be set to true,
+ <code>chargingTime</code> to 0, <code>level</code> to 1.0 and
+ <code>dischargingTime</code> to the value positive Infinity respectively.
</p>
<p>
The <code>charging</code> attribute MUST be set to false if the battery
@@ -325,6 +352,31 @@
</code> events are fired is left to the implementation.
</div>
<section>
+ <h2>Multiple batteries</h2>
+ <p>
+ If a hosting device contains more than one battery,
+ <a>BatteryManager</a> SHOULD expose an unified view of the batteries.
+ </p>
+ <p>
+ The <code>charging</code> attribute MUST be set to true if at least
+ one battery's <code>charging</code> state as described above is true.
+ Otherwise, it MUST be set to false.
+ </p>
+ <p>
+ The <code>level</code> attribute MUST be set to the sum of the
+ individual battery's <code>level</code> attributes divided by the
+ number of batteries.
+ </p>
+ <p>
+ The <code>chargingTime</code> attribute MUST be set to the max of all
+ the individual batteries <code>chargingTime</code>.
+ </p>
+ <p>
+ The <code>dischargingTime</code> attribute MUST be set to the max of
+ all the individual batteries <code>dischargingTime</code>.
+ </p>
+ </section>
+ <section>
<h2>Event handlers</h2>
<p>
The following are the <a>event handlers</a> (and their corresponding
@@ -367,18 +419,22 @@
the level changes:
</p>
<pre class="example highlight">
- navigator.battery.onlevelchange = function () {
- console.log(navigator.battery.level);
- };
+ navigator.getBattery(function(battery) {
+ battery.onlevelchange = function() {
+ console.log(this.level);
+ };
+ });
</pre>
<p>
Alternatively, the same using the <code>addEventListener()</code>
method:
</p>
<pre class="example highlight">
- navigator.battery.addEventListener('levelchange', function () {
- console.log(navigator.battery.level);
- }, false);
+ navigator.getBattery(function(battery) {
+ battery.addEventListener('levelchange', function() {
+ console.log(this.level);
+ });
+ });
</pre>
<p>
The following example updates the indicators to show the charging
@@ -390,19 +446,19 @@
<head>
<title>Battery Status API Example</title>
<script>
- var battery = navigator.battery;
-
- battery.onchargingchange = function () {
- document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
- };
+ navigator.getBattery().then(function(battery) {
+ battery.onchargingchange = function () {
+ document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
+ };
- battery.onlevelchange = function () {
- document.querySelector('#level').textContent = battery.level;
- };
+ battery.onlevelchange = function () {
+ document.querySelector('#level').textContent = battery.level;
+ };
- battery.ondischargingtimechange = function () {
- document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
- };
+ battery.ondischargingtimechange = function () {
+ document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
+ };
+ });
</script>
</head>
<body>