Add rationale for the BatteryManager's default attribute values.
authorAnssi Kostiainen <anssi.kostiainen@intel.com>
Mon, 16 Jun 2014 14:12:47 +0300
changeset 542 4c334400e0aa
parent 541 c799dd856942
child 543 8a9320b0e7d1
Add rationale for the BatteryManager's default attribute values.
battery/Overview.html
battery/Overview.src.html
--- a/battery/Overview.html	Mon Jun 16 10:14:01 2014 +0300
+++ b/battery/Overview.html	Mon Jun 16 14:12:47 2014 +0300
@@ -436,7 +436,7 @@
   </p>
   <h1 class="title p-name" id="title" property="dcterms:title">Battery Status API</h1>
   
-  <h2 property="dcterms:issued" datatype="xsd:dateTime" content="2014-06-10T07:58:01.000Z" id="w3c-editor-s-draft-10-june-2014"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft <time class="dt-published" datetime="2014-06-10">10 June 2014</time></h2>
+  <h2 property="dcterms:issued" datatype="xsd:dateTime" content="2014-06-16T08:02:23.000Z" id="w3c-editor-s-draft-16-june-2014"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft <time class="dt-published" datetime="2014-06-16">16 June 2014</time></h2>
   <dl>
     
       <dt>This version:</dt>
@@ -826,6 +826,15 @@
         system is about to be suspended, and the <code>level</code> attribute 
         represents the level of the system's battery.
       </p>
+      <p>
+        If the implementation is unable to report the battery status
+        information for a particular attribute, the <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> will
+        emulate a fully charged battery by setting the attribute's value to a
+        value that of the fully charged battery. This prevents leaking of
+        information that could be used to fingerprint a user and allow web
+        developers to use the same code path for handling battery full and
+        battery status unknown cases.
+      </p>
       <pre class="idl"><span class="idlInterface" id="idl-def-BatteryManager">interface <span class="idlInterfaceID">BatteryManager</span> : <span class="idlSuperclass">EventTarget</span> {
 <span class="idlAttribute">    readonly    attribute <span class="idlAttrType">boolean</span>             <span class="idlAttrName"><a href="#widl-BatteryManager-charging">charging</a></span>;</span>
 <span class="idlAttribute">    readonly    attribute <span class="idlAttrType">unrestricted double</span> <span class="idlAttrName"><a href="#widl-BatteryManager-chargingTime">chargingTime</a></span>;</span>
@@ -856,10 +865,6 @@
           level, the <code>level</code> attribute must be set to 1.0.
         </li>
       </ul>
-      <div class="note"><div class="note-title" aria-level="2" role="heading" id="h_note_1"><span>Note</span></div><div class="">
-        The <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a>'s default attribute values emulate a fully
-        charged battery.
-      </div></div>
       <p>
         The <code>charging</code> attribute <em class="rfc2119" title="MUST">MUST</em> be set to false if the battery
         is discharging, and set to true, if the battery is charging, the
@@ -901,7 +906,7 @@
         <a href="#dfn-fires-a-simple-event" class="internalDFN">fires a simple event</a> named <code><a href="#dfn-levelchange" class="internalDFN">levelchange</a></code> at
         the <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object.
       </p>
-      <div class="note"><div class="note-title" aria-level="2" role="heading" id="h_note_2"><span>Note</span></div><div class="">
+      <div class="note"><div class="note-title" aria-level="2" role="heading" id="h_note_1"><span>Note</span></div><div class="">
         The definition of how often the <code><a href="#dfn-chargingtimechange" class="internalDFN">chargingtimechange</a></code>,
         <code><a href="#dfn-dischargingtimechange" class="internalDFN">dischargingtimechange</a></code>, and <code><a href="#dfn-levelchange" class="internalDFN">levelchange</a>
         </code> events are fired is left to the implementation.
@@ -1039,6 +1044,6 @@
 
 <section id="references" class="appendix" typeof="bibo:Chapter" resource="#references" rel="bibo:Chapter"><!--OddPage--><h2 aria-level="1" role="heading" id="h2_references"><span class="secno">B. </span>References</h2><section id="normative-references" typeof="bibo:Chapter" resource="#normative-references" rel="bibo:Chapter"><h3 aria-level="2" role="heading" id="h3_normative-references"><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography" about=""><dt id="bib-ECMASCRIPT">[ECMASCRIPT]</dt><dd rel="dcterms:requires"><a href="http://people.mozilla.org/~jorendorff/es6-draft.html"><cite>ECMA-262 ECMAScript Language Specification, Edition 6</cite></a>. Draft. URL: <a href="http://people.mozilla.org/~jorendorff/es6-draft.html">http://people.mozilla.org/~jorendorff/es6-draft.html</a>
 </dd><dt id="bib-HTML5">[HTML5]</dt><dd rel="dcterms:requires">Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. <a href="http://www.w3.org/TR/html5/"><cite>HTML5</cite></a>. 29 April 2014. W3C Candidate Recommendation. URL: <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a>
-</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd rel="dcterms:requires">S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119.  URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a> 
+</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd rel="dcterms:requires">S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
 </dd><dt id="bib-WEBIDL">[WEBIDL]</dt><dd rel="dcterms:requires">Cameron McCormack. <a href="http://www.w3.org/TR/WebIDL/"><cite>Web IDL</cite></a>. 19 April 2012. W3C Candidate Recommendation. URL: <a href="http://www.w3.org/TR/WebIDL/">http://www.w3.org/TR/WebIDL/</a>
 </dd></dl></section></section></body></html>
\ No newline at end of file
--- a/battery/Overview.src.html	Mon Jun 16 10:14:01 2014 +0300
+++ b/battery/Overview.src.html	Mon Jun 16 14:12:47 2014 +0300
@@ -296,6 +296,15 @@
         system is about to be suspended, and the <code>level</code> attribute 
         represents the level of the system's battery.
       </p>
+      <p>
+        If the implementation is unable to report the battery status
+        information for a particular attribute, the <a>BatteryManager</a> will
+        emulate a fully charged battery by setting the attribute's value to a
+        value that of the fully charged battery. This prevents leaking of
+        information that could be used to fingerprint a user and allow web
+        developers to use the same code path for handling battery full and
+        battery status unknown cases.
+      </p>
       <dl title="interface BatteryManager : EventTarget"
           class="idl">
         <dt>readonly attribute boolean charging</dt>
@@ -343,10 +352,6 @@
           level, the <code>level</code> attribute must be set to 1.0.
         </li>
       </ul>
-      <div class="note">
-        The <a>BatteryManager</a>'s default attribute values emulate a fully
-        charged battery.
-      </div>
       <p>
         The <code>charging</code> attribute MUST be set to false if the battery
         is discharging, and set to true, if the battery is charging, the