--- a/battery/Overview.html Thu Aug 20 15:50:38 2015 +0300
+++ b/battery/Overview.html Thu Mar 17 16:00:35 2016 +0200
@@ -1,1071 +1,10 @@
<!DOCTYPE html>
-<html lang="en" dir="ltr" typeof="bibo:Document " prefix="bibo: http://purl.org/ontology/bibo/ w3p: http://www.w3.org/2001/02pd/rec54#">
-<head><meta lang="" property="dc:language" content="en">
+<html>
+ <head>
<title>Battery Status API</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
-
-
- <style>/*****************************************************************
- * ReSpec 3 CSS
- * Robin Berjon - http://berjon.com/
- *****************************************************************/
-
-/* --- INLINES --- */
-em.rfc2119 {
- text-transform: lowercase;
- font-variant: small-caps;
- font-style: normal;
- color: #900;
-}
-
-h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
-h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
- border: none;
-}
-
-dfn {
- font-weight: bold;
-}
-
-a.internalDFN {
- color: inherit;
- border-bottom: 1px solid #99c;
- text-decoration: none;
-}
-
-a.externalDFN {
- color: inherit;
- border-bottom: 1px dotted #ccc;
- text-decoration: none;
-}
-
-a.bibref {
- text-decoration: none;
-}
-
-cite .bibref {
- font-style: normal;
-}
-
-code {
- color: #C83500;
-}
-
-/* --- TOC --- */
-.toc a, .tof a {
- text-decoration: none;
-}
-
-a .secno, a .figno {
- color: #000;
-}
-
-ul.tof, ol.tof {
- list-style: none outside none;
-}
-
-.caption {
- margin-top: 0.5em;
- font-style: italic;
-}
-
-/* --- TABLE --- */
-table.simple {
- border-spacing: 0;
- border-collapse: collapse;
- border-bottom: 3px solid #005a9c;
-}
-
-.simple th {
- background: #005a9c;
- color: #fff;
- padding: 3px 5px;
- text-align: left;
-}
-
-.simple th[scope="row"] {
- background: inherit;
- color: inherit;
- border-top: 1px solid #ddd;
-}
-
-.simple td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
-}
-
-.simple tr:nth-child(even) {
- background: #f0f6ff;
-}
-
-/* --- DL --- */
-.section dd > p:first-child {
- margin-top: 0;
-}
-
-.section dd > p:last-child {
- margin-bottom: 0;
-}
-
-.section dd {
- margin-bottom: 1em;
-}
-
-.section dl.attrs dd, .section dl.eldef dd {
- margin-bottom: 0;
-}
-
-@media print {
- .removeOnSave {
- display: none;
- }
-}
-</style><style>/* --- EXAMPLES --- */
-div.example-title {
- min-width: 7.5em;
- color: #b9ab2d;
-}
-div.example-title span {
- text-transform: uppercase;
-}
-aside.example, div.example, div.illegal-example {
- padding: 0.5em;
- margin: 1em 0;
- position: relative;
- clear: both;
-}
-div.illegal-example { color: red }
-div.illegal-example p { color: black }
-aside.example, div.example {
- padding: .5em;
- border-left-width: .5em;
- border-left-style: solid;
- border-color: #e0cb52;
- background: #fcfaee;
-}
-
-aside.example div.example {
- border-left-width: .1em;
- border-color: #999;
- background: #fff;
-}
-aside.example div.example div.example-title {
- color: #999;
-}
-</style><style>/* --- ISSUES/NOTES --- */
-div.issue-title, div.note-title , div.ednote-title, div.warning-title {
- padding-right: 1em;
- min-width: 7.5em;
- color: #b9ab2d;
-}
-div.issue-title { color: #e05252; }
-div.note-title, div.ednote-title { color: #2b2; }
-div.warning-title { color: #f22; }
-div.issue-title span, div.note-title span, div.ednote-title span, div.warning-title span {
- text-transform: uppercase;
-}
-div.note, div.issue, div.ednote, div.warning {
- margin-top: 1em;
- margin-bottom: 1em;
-}
-.note > p:first-child, .ednote > p:first-child, .issue > p:first-child, .warning > p:first-child { margin-top: 0 }
-.issue, .note, .ednote, .warning {
- padding: .5em;
- border-left-width: .5em;
- border-left-style: solid;
-}
-div.issue, div.note , div.ednote, div.warning {
- padding: 1em 1.2em 0.5em;
- margin: 1em 0;
- position: relative;
- clear: both;
-}
-span.note, span.ednote, span.issue, span.warning { padding: .1em .5em .15em; }
-
-.issue {
- border-color: #e05252;
- background: #fbe9e9;
-}
-.note, .ednote {
- border-color: #52e052;
- background: #e9fbe9;
-}
-
-.warning {
- border-color: #f11;
- border-right-width: .2em;
- border-top-width: .2em;
- border-bottom-width: .2em;
- border-style: solid;
- background: #fbe9e9;
-}
-
-.warning-title:before{
- content: "⚠"; /*U+26A0 WARNING SIGN*/
- font-size: 3em;
- float: left;
- height: 100%;
- padding-right: .3em;
- vertical-align: top;
- margin-top: -0.5em;
-}
-
-li.task-list-item {
- list-style: none;
-}
-
-input.task-list-item-checkbox {
- margin: 0 0.35em 0.25em -1.6em;
- vertical-align: middle;
-}
-</style><style>/* HIGHLIGHTS */
-code.prettyprint {
- color: inherit;
-}
-
-/* this from google-code-prettify */
-.pln{color:#000}@media screen{.str{color:#080}.kwd{color:#008}.com{color:#800}.typ{color:#606}.lit{color:#066}.pun,.opn,.clo{color:#660}.tag{color:#008}.atn{color:#606}.atv{color:#080}.dec,.var{color:#606}.fun{color:red}}@media print,projection{.str{color:#060}.kwd{color:#006;font-weight:bold}.com{color:#600;font-style:italic}.typ{color:#404;font-weight:bold}.lit{color:#044}.pun,.opn,.clo{color:#440}.tag{color:#006;font-weight:bold}.atn{color:#404}.atv{color:#060}}ol.linenums{margin-top:0;margin-bottom:0}li.L0,li.L1,li.L2,li.L3,li.L5,li.L6,li.L7,li.L8{list-style-type:none}li.L1,li.L3,li.L5,li.L7,li.L9{background:#eee}
-</style><style>/* --- WEB IDL --- */
-pre.idl {
- border-top: 1px solid #90b8de;
- border-bottom: 1px solid #90b8de;
- padding: 1em;
- line-height: 120%;
-}
-
-pre.idl::before {
- content: "WebIDL";
- display: block;
- width: 150px;
- background: #90b8de;
- color: #fff;
- font-family: sans-serif;
- padding: 3px;
- font-weight: bold;
- margin: -1em 0 1em -1em;
-}
-
-.idlType {
- color: #ff4500;
- font-weight: bold;
- text-decoration: none;
-}
-
-/*.idlModule*/
-/*.idlModuleID*/
-/*.idlInterface*/
-.idlInterfaceID, .idlDictionaryID, .idlCallbackID, .idlEnumID {
- font-weight: bold;
- color: #005a9c;
-}
-a.idlEnumItem {
- color: #000;
- border-bottom: 1px dotted #ccc;
- text-decoration: none;
-}
-
-.idlSuperclass {
- font-style: italic;
- color: #005a9c;
-}
-
-/*.idlAttribute*/
-.idlAttrType, .idlFieldType, .idlMemberType {
- color: #005a9c;
-}
-.idlAttrName, .idlFieldName, .idlMemberName {
- color: #ff4500;
-}
-.idlAttrName a, .idlFieldName a, .idlMemberName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlMethod*/
-.idlMethType, .idlCallbackType {
- color: #005a9c;
-}
-.idlMethName {
- color: #ff4500;
-}
-.idlMethName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlCtor*/
-.idlCtorName {
- color: #ff4500;
-}
-.idlCtorName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlParam*/
-.idlParamType {
- color: #005a9c;
-}
-.idlParamName, .idlDefaultValue {
- font-style: italic;
-}
-
-.extAttr {
- color: #666;
-}
-
-/*.idlSectionComment*/
-.idlSectionComment {
- color: gray;
-}
-
-/*.idlIterable*/
-.idlIterableKeyType, .idlIterableValueType {
- color: #005a9c;
-}
-
-/*.idlMaplike*/
-.idlMaplikeKeyType, .idlMaplikeValueType {
- color: #005a9c;
-}
-
-/*.idlConst*/
-.idlConstType {
- color: #005a9c;
-}
-.idlConstName {
- color: #ff4500;
-}
-.idlConstName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlException*/
-.idlExceptionID {
- font-weight: bold;
- color: #c00;
-}
-
-.idlTypedefID, .idlTypedefType {
- color: #005a9c;
-}
-
-.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
- color: #c00;
- font-weight: normal;
-}
-
-.excName a {
- font-family: monospace;
-}
-
-.idlRaises a.idlType, .excName a.idlType {
- border-bottom: 1px dotted #c00;
-}
-
-.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
- width: 45px;
- text-align: center;
-}
-.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
-.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
-
-.idlImplements a {
- font-weight: bold;
-}
-
-dl.attributes, dl.methods, dl.constants, dl.constructors, dl.fields, dl.dictionary-members {
- margin-left: 2em;
-}
-
-.attributes dt, .methods dt, .constants dt, .constructors dt, .fields dt, .dictionary-members dt {
- font-weight: normal;
-}
-
-.attributes dt code, .methods dt code, .constants dt code, .constructors dt code, .fields dt code, .dictionary-members dt code {
- font-weight: bold;
- color: #000;
- font-family: monospace;
-}
-
-.attributes dt code, .fields dt code, .dictionary-members dt code {
- background: #ffffd2;
-}
-
-.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
- color: #005a9c;
- background: transparent;
- font-family: inherit;
- font-weight: normal;
- font-style: italic;
-}
-
-.methods dt code {
- background: #d9e6f8;
-}
-
-.constants dt code {
- background: #ddffd2;
-}
-
-.constructors dt code {
- background: #cfc;
-}
-
-.attributes dd, .methods dd, .constants dd, .constructors dd, .fields dd, .dictionary-members dd {
- margin-bottom: 1em;
-}
-
-table.parameters, table.exceptions {
- border-spacing: 0;
- border-collapse: collapse;
- margin: 0.5em 0;
- width: 100%;
-}
-table.parameters { border-bottom: 1px solid #90b8de; }
-table.exceptions { border-bottom: 1px solid #deb890; }
-
-.parameters th, .exceptions th {
- color: #fff;
- padding: 3px 5px;
- text-align: left;
- font-weight: normal;
- text-shadow: #666 1px 1px 0;
-}
-.parameters th { background: #90b8de; }
-.exceptions th { background: #deb890; }
-
-.parameters td, .exceptions td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
- vertical-align: top;
-}
-
-.parameters tr:first-child td, .exceptions tr:first-child td {
- border-top: none;
-}
-
-.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
- width: 100px;
-}
-
-.parameters td.prmType {
- width: 120px;
-}
-
-table.exceptions table {
- border-spacing: 0;
- border-collapse: collapse;
- width: 100%;
-}
-</style><link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/W3C-ED"><!--[if lt IE 9]><script src='https://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
- <body class="h-entry" role="document" id="respecDocument"><div class="head" role="contentinfo" id="respecHeader">
- <p>
-
-
- <a href="http://www.w3.org/"><img width="72" height="48" src="https://www.w3.org/Icons/w3c_home" alt="W3C"></a>
-
-
-
-
- </p>
- <h1 class="title p-name" id="title" property="dcterms:title">Battery Status API</h1>
-
- <h2 id="w3c-editor-s-draft-20-august-2015"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft <time property="dcterms:issued" class="dt-published" datetime="2015-08-20">20 August 2015</time></h2>
- <dl>
-
- <dt>This version:</dt>
- <dd><a class="u-url" href="https://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html">https://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html</a></dd>
- <dt>Latest published version:</dt>
- <dd><a href="http://www.w3.org/TR/battery-status/">http://www.w3.org/TR/battery-status/</a></dd>
-
-
- <dt>Latest editor's draft:</dt>
- <dd><a href="https://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html">https://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html</a></dd>
-
-
- <dt>Test suite:</dt>
- <dd><a href="http://w3c-test.org/battery-status/">http://w3c-test.org/battery-status/</a></dd>
-
-
- <dt>Implementation report:</dt>
- <dd><a href="http://www.w3.org/2009/dap/wiki/ImplementationStatus">http://www.w3.org/2009/dap/wiki/ImplementationStatus</a></dd>
-
-
-
-
-
-
-
- <dt>Editors:</dt>
- <dd class="p-author h-card vcard" property="bibo:editor" resource="_:editor0"><span property="rdf:first" typeof="foaf:Person"><span property="foaf:name" class="p-name fn">Anssi Kostiainen</span>, <a property="foaf:workplaceHomepage" class="p-org org h-org h-card" href="http://intel.com/">Intel</a></span>
-<span property="rdf:rest" resource="_:editor1"></span>
-</dd>
-<dd class="p-author h-card vcard" resource="_:editor1"><span property="rdf:first" typeof="foaf:Person"><span property="foaf:name" class="p-name fn">Mounir Lamouri</span>, <a property="foaf:workplaceHomepage" class="p-org org h-org h-card" href="http://google.com/">Google Inc.</a> (previously Mozilla)</span>
-<span property="rdf:rest" resource="rdf:nil"></span>
-</dd>
-
-
-
- </dl>
-
-
-
-
-
- <p class="copyright">
- <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
- 2015
-
- <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
- (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
- <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
- <a href="http://www.keio.ac.jp/">Keio</a>, <a href="http://ev.buaa.edu.cn/">Beihang</a>).
-
- <abbr title="World Wide Web Consortium">W3C</abbr> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
- <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and
-
- <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a>
-
- rules apply.
- </p>
-
-
- <hr>
-</div>
- <section id="abstract" class="introductory" property="dc:abstract"><h2 id="h-abstract" resource="#h-abstract"><span property="xhv:role" resource="xhv:heading">Abstract</span></h2><p>
- This specification defines an API that provides information about the
- battery status of the hosting device.
- </p></section><section id="sotd" class="introductory"><h2 id="h-sotd" resource="#h-sotd"><span property="xhv:role" resource="xhv:heading">Status of This Document</span></h2>
-
-
-
- <p>
- <em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports index</a> at http://www.w3.org/TR/.</em>
- </p>
-
-
-
- <p>
- The functionality described in this specification was initially
- specified as part of the
- <a href="http://www.w3.org/TR/system-info-api/">System Information
- API</a> but has been extracted in order to be more readily available,
- more straightforward to implement, and in order to produce a
- specification that could be implemented on its own merits without
- interference with other, often unrelated, features.
- </p>
- <p>
- No substantial changes have been made since the
- <a href="http://www.w3.org/TR/2014/WD-battery-status-20140828/">
- <abbr title="World Wide Web Consortium">W3C</abbr> Last Call Working Draft 28 August 2014</a>
- (<a href="CR2-diff.html">diff</a>).
- </p>
- <p>
- The CR exit criterion is two interoperable deployed implementations of
- each feature. No features are marked as 'at-risk'.
- </p>
-
-
- <p>
- This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs Working Group</a> as an Editor's Draft.
-
-
- If you wish to make comments regarding this document, please send them to
- <a href="mailto:public-device-apis@w3.org">public-device-apis@w3.org</a>
- (<a href="mailto:public-device-apis-request@w3.org?subject=subscribe">subscribe</a>,
- <a href="http://lists.w3.org/Archives/Public/public-device-apis/">archives</a>).
-
-
-
-
-
-
- All comments are welcome.
-
-
- </p>
-
- <p>
- Please see the Working Group's <a href="http://www.w3.org/2009/dap/wiki/ImplementationStatus">implementation
- report</a>.
- </p>
-
-
-
- <p>
- Publication as an Editor's Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr>
- Membership. This is a draft document and may be updated, replaced or obsoleted by other
- documents at any time. It is inappropriate to cite this document as other than work in
- progress.
- </p>
-
-
-
- <p>
-
- This document was produced by a group operating under the
- <a id="sotd_patent" property="w3p:patentRules" href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent
- Policy</a>.
-
-
-
-
- <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/43696/status" rel="disclosure">public list of any patent
- disclosures</a>
-
- made in connection with the deliverables of the group; that page also includes
- instructions for disclosing a patent. An individual who has actual knowledge of a patent
- which the individual believes contains
- <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
- Claim(s)</a> must disclose the information in accordance with
- <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
- 6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
-
-
- </p>
-
- <p>
- This document is governed by the <a id="w3c_process_revision" href="http://www.w3.org/2005/10/Process-20051014/">14 October 2005 <abbr title="World Wide Web Consortium">W3C</abbr> Process Document</a>.
- </p>
-
-
-
-
-
-
-</section><section id="toc"><h2 class="introductory" id="h-toc" resource="#h-toc"><span property="xhv:role" resource="xhv:heading">Table of Contents</span></h2><ul class="toc" role="directory" id="respecContents"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">2. </span>Conformance</a></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#security-and-privacy-considerations" class="tocxref"><span class="secno">4. </span>Security and privacy considerations</a></li><li class="tocline"><a href="#the-navigator-interface" class="tocxref"><span class="secno">5. </span>The <span class="formerLink"><code>Navigator</code></span> interface</a></li><li class="tocline"><a href="#the-batterymanager-interface" class="tocxref"><span class="secno">6. </span>The <span class="formerLink"><code>BatteryManager</code></span> interface</a><ul class="toc"><li class="tocline"><a href="#multiple-batteries" class="tocxref"><span class="secno">6.1 </span>Multiple batteries</a></li><li class="tocline"><a href="#event-handlers" class="tocxref"><span class="secno">6.2 </span>Event handlers</a></li></ul></li><li class="tocline"><a href="#examples" class="tocxref"><span class="secno">7. </span>Examples</a></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li></ul></li></ul></section>
-
-
-
- <section class="informative" id="introduction" typeof="bibo:Chapter" resource="#introduction" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-introduction" resource="#h-introduction"><span property="xhv:role" resource="xhv:heading"><span class="secno">1. </span>Introduction</span></h2><p><em>This section is non-normative.</em></p>
- <p>
- The Battery Status API specification defines a means for web
- developers to programmatically determine the battery status of the
- hosting device. Without knowing the battery status of a device, a web
- developer must design the web application with an assumption of
- sufficient battery level for the task at hand. This means the battery
- of a device may exhaust faster than desired because web developers are
- unable to make decisions based on the battery status. Given knowledge
- of the battery status, web developers are able to craft web content and
- applications which are power-efficient, thereby leading to improved
- user experience. Authors should be aware, however, that a naïve
- implementation of this API can negatively affect the battery life.
- </p>
- <p>
- The Battery Status API can be used to defer or scale back work when
- the device is not charging in or is low on battery. An archetype of an
- advanced web application, a web-based email client, may check the
- server for new email every few seconds if the device is charging,
- but do so less frequently if the device is not charging or is low on
- battery. Another example is a web-based word processor which could
- monitor the battery level and save changes before the battery runs
- out to prevent data loss.
- </p>
- </section>
-
- <section id="conformance" typeof="bibo:Chapter" resource="#conformance" property="bibo:hasPart"><!--OddPage--><h2 id="h-conformance" resource="#h-conformance"><span property="xhv:role" resource="xhv:heading"><span class="secno">2. </span>Conformance</span></h2>
-<p>
- As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
- and notes in this specification are non-normative. Everything else in this specification is
- normative.
-</p>
-<p id="respecRFC2119">The key words <em class="rfc2119" title="MAY">MAY</em>, <em class="rfc2119" title="MUST">MUST</em>, <em class="rfc2119" title="MUST NOT">MUST NOT</em>, and <em class="rfc2119" title="SHOULD">SHOULD</em> are
- to be interpreted as described in [<cite><a class="bibref" href="#bib-RFC2119">RFC2119</a></cite>].
-</p>
-
- <p>
- This specification defines conformance criteria that apply to a single
- product: the <dfn data-dfn-type="dfn" id="dfn-user-agent">user agent</dfn> that implements the
- interfaces that it contains.
- </p>
- <p>
- Implementations that use ECMAScript to implement the APIs defined in
- this specification must implement them in a manner consistent with the
- ECMAScript Bindings defined in the Web IDL specification [<cite><a class="bibref" href="#bib-WEBIDL">WEBIDL</a></cite>],
- as this specification uses that specification and terminology.
- </p>
- </section>
- <section id="terminology" typeof="bibo:Chapter" resource="#terminology" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-terminology" resource="#h-terminology"><span property="xhv:role" resource="xhv:heading"><span class="secno">3. </span>Terminology</span></h2>
- <p>
- The following concepts, terms and interfaces are defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>]:
- </p>
- <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 data-dfn-type="dfn" id="dfn-queue-a-task"><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
- queue a task</a></dfn></li>
- <li><dfn data-dfn-type="dfn" id="dfn-fires-a-simple-event"><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
- fires a simple event</a></dfn></li>
- <li><dfn data-dfn-type="dfn" id="dfn-event-handlers"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
- event handlers</a></dfn></li>
- <li><dfn data-dfn-type="dfn" id="dfn-event-handler-event-types"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
- event handler event types</a></dfn></li>
- <li><dfn data-dfn-type="dfn" id="dfn-browsing-context"><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
- browsing context</a></dfn></li>
- </ul>
- <p>
- <a href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects">
- <dfn data-dfn-type="dfn" id="dfn-promise">Promise</dfn></a> objects are defined in [<cite><a class="bibref" href="#bib-ECMASCRIPT">ECMASCRIPT</a></cite>].
- </p>
- </section>
- <section class="informative" id="security-and-privacy-considerations" typeof="bibo:Chapter" resource="#security-and-privacy-considerations" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-security-and-privacy-considerations" resource="#h-security-and-privacy-considerations"><span property="xhv:role" resource="xhv:heading"><span class="secno">4. </span>Security and privacy considerations</span></h2><p><em>This section is non-normative.</em></p>
- <p>
- The API defined in this specification is used to determine the battery
- status of the hosting device.
- </p>
- <p>
- The user agent <em class="rfc2119" title="SHOULD">SHOULD</em> not expose high precision readouts of battery
- status information as that can introduce a new fingerprinting vector.
- </p>
- <p>
- The user agent <em class="rfc2119" title="MAY">MAY</em> ask the user for battery status information access, or
- alternatively, enforce the user permission requirement in its private
- browsing modes.
- </p>
- <p>
- The user agent <em class="rfc2119" title="SHOULD">SHOULD</em> inform the user of the API use by scripts in an
- unobtrusive manner to aid transparency and to allow the user to revoke
- the API access.
- </p>
- <p>
- The user agent <em class="rfc2119" title="MAY">MAY</em> 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 id="the-navigator-interface" typeof="bibo:Chapter" resource="#the-navigator-interface" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-the-navigator-interface" resource="#h-the-navigator-interface"><span property="xhv:role" resource="xhv:heading"><span class="secno">5. </span>The <a href="#idl-def-Navigator" class="idlType"><code>Navigator</code></a> interface</span></h2>
- <pre class="idl"><span class="idlInterface" id="idl-def-Navigator">partial interface <span class="idlInterfaceID">Navigator</span> {
-<span class="idlMethod"> <span class="idlMethType">Promise<<a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a>></span> <span class="idlMethName"><a href="#widl-Navigator-getBattery-Promise-BatteryManager">getBattery</a></span> ();</span>
-};</span></pre>
- <p>
- For each <a href="#dfn-browsing-context" class="internalDFN" data-link-type="dfn">browsing context</a>, there is a <dfn data-dfn-type="dfn" id="dfn-battery-promise">battery promise</dfn>,
- which is initially set to <code>null</code>. It is a <a href="#dfn-promise" class="internalDFN" data-link-type="dfn">Promise</a>
- object which holds a <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a>.
- </p>
- <p>
- The <code id="widl-Navigator-getBattery-Promise-BatteryManager">getBattery()</code>
- method, when invoked, <em class="rfc2119" title="MUST">MUST</em> run the following steps:
- </p>
- <ul>
- <li>
- If <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery promise</a> is not <code>null</code>, return <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery
- promise</a> and abort these steps.
- </li>
- <li>
- Otherwise, set <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery promise</a> to a newly created
- <a href="#dfn-promise" class="internalDFN" data-link-type="dfn">Promise</a>.
- </li>
- <li>
- Return <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery promise</a> and continue asynchronously.
- </li>
- <li>
- <a href="#dfn-create-a-new-batterymanager-object" class="internalDFN" data-link-type="dfn">Create a new <code>BatteryManager</code> object</a>,
- and let <var>battery</var> be that object.
- </li>
- <li>
- <dfn data-dfn-type="dfn" id="dfn-resolve">Resolve</dfn> <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery promise</a> with <var>battery</var>.
- </li>
- </ul>
- <p>
- The <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> <em class="rfc2119" title="MUST NOT">MUST NOT</em> reject the <a href="#dfn-battery-promise" class="internalDFN" data-link-type="dfn">battery promise</a>.
- </p>
- </section>
-
- <section id="the-batterymanager-interface" typeof="bibo:Chapter" resource="#the-batterymanager-interface" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-the-batterymanager-interface" resource="#h-the-batterymanager-interface"><span property="xhv:role" resource="xhv:heading"><span class="secno">6. </span>The <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> interface</span></h2>
- <p>
- The <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> interface represents the <dfn data-dfn-type="dfn" id="dfn-current-battery-status-information">current battery
- status information</dfn> of the hosting device. The <code>charging</code>
- attribute represents the charging state of the system's battery.
- The <code>chargingTime</code> attribute represents the time remaining
- in seconds until the system's battery is fully charged. The
- <code>dischargingTime</code> 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 <code>level</code> attribute
- represents the level of the system's battery.
- </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>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType">unrestricted double</span> <span class="idlAttrName"><a href="#widl-BatteryManager-dischargingTime">dischargingTime</a></span>;</span>
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType">double</span> <span class="idlAttrName"><a href="#widl-BatteryManager-level">level</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType">EventHandler</span> <span class="idlAttrName"><a href="#widl-BatteryManager-onchargingchange">onchargingchange</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType">EventHandler</span> <span class="idlAttrName"><a href="#widl-BatteryManager-onchargingtimechange">onchargingtimechange</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType">EventHandler</span> <span class="idlAttrName"><a href="#widl-BatteryManager-ondischargingtimechange">ondischargingtimechange</a></span>;</span>
-<span class="idlAttribute"> attribute <span class="idlAttrType">EventHandler</span> <span class="idlAttrName"><a href="#widl-BatteryManager-onlevelchange">onlevelchange</a></span>;</span>
-};</span></pre>
- <p>
- When the <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> is to <dfn data-dfn-type="dfn" id="dfn-create-a-new-batterymanager-object">create a new
- <code>BatteryManager</code> object</dfn>, it <em class="rfc2119" title="MUST">MUST</em> instantiate a new
- <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object and set its attributes' values to those
- that represent the <a href="#dfn-current-battery-status-information" class="internalDFN" data-link-type="dfn">current battery status information</a>, unless
- the <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> is <a href="#dfn-unable-to-report-the-battery-status-information" class="internalDFN" data-link-type="dfn">unable to report the battery status
- information</a>, in which case the values <em class="rfc2119" title="MUST">MUST</em> be set to <dfn data-dfn-type="dfn" id="dfn-default-values">default
- values</dfn> as follows:
- <code>charging</code> <em class="rfc2119" title="MUST">MUST</em> be set to true,
- <code>chargingTime</code> <em class="rfc2119" title="MUST">MUST</em> be set to 0,
- <code>dischargingTime</code> <em class="rfc2119" title="MUST">MUST</em> be set to positive Infinity, and
- <code>level</code> <em class="rfc2119" title="MUST">MUST</em> be set to 1.0.
- </p>
- <p>
- The <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> is said to be <dfn data-dfn-type="dfn" id="dfn-unable-to-report-the-battery-status-information">unable to report the
- battery status information</dfn>, 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.
- </p>
- <div class="note"><div class="note-title" aria-level="3" role="heading" id="h-note1"><span>Note</span></div><p class="">
- Implementations <a href="#dfn-unable-to-report-the-battery-status-information" class="internalDFN" data-link-type="dfn">unable to report the battery status information</a>
- 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.
- </p></div>
- <p>
- The <code id="widl-BatteryManager-charging">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
- 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 <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> <em class="rfc2119" title="MUST">MUST</em> <a href="#dfn-queue-a-task" class="internalDFN" data-link-type="dfn">queue a task</a> which sets
- the <code>charging</code> attribute's value and <a href="#dfn-fires-a-simple-event" class="internalDFN" data-link-type="dfn">fires a simple
- event</a> named <code><a href="#dfn-chargingchange" class="internalDFN" data-link-type="dfn"><code>chargingchange</code></a></code> at the
- <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-chargingTime">chargingTime</code>
- attribute <em class="rfc2119" title="MUST">MUST</em> 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 <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user
- agent</a> <em class="rfc2119" title="MUST">MUST</em> <a href="#dfn-queue-a-task" class="internalDFN" data-link-type="dfn">queue a task</a> which sets the
- <code>chargingTime</code> attribute's value and <a href="#dfn-fires-a-simple-event" class="internalDFN" data-link-type="dfn">fires a simple
- event</a> named <code><a href="#dfn-chargingtimechange" class="internalDFN" data-link-type="dfn"><code>chargingtimechange</code></a></code> at the
- <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-dischargingTime">dischargingTime</code>
- attribute <em class="rfc2119" title="MUST">MUST</em> 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 <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> <em class="rfc2119" title="MUST">MUST</em> <a href="#dfn-queue-a-task" class="internalDFN" data-link-type="dfn">queue a task</a> which sets
- the <code>dischargingTime</code> attribute's value and <a href="#dfn-fires-a-simple-event" class="internalDFN" data-link-type="dfn">fires a
- simple event </a> named <code><a href="#dfn-dischargingtimechange" class="internalDFN" data-link-type="dfn"><code>dischargingtimechange</code></a></code> at the
- <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-level">level</code>
- attribute <em class="rfc2119" title="MUST">MUST</em> 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 <a href="#dfn-user-agent" class="internalDFN" data-link-type="dfn">user agent</a> <em class="rfc2119" title="MUST">MUST</em> <a href="#dfn-queue-a-task" class="internalDFN" data-link-type="dfn">queue a
- task</a> which sets the <code>level</code> attribute's value and
- <a href="#dfn-fires-a-simple-event" class="internalDFN" data-link-type="dfn">fires a simple event</a> named <code><a href="#dfn-levelchange" class="internalDFN" data-link-type="dfn"><code>levelchange</code></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="3" role="heading" id="h-note2"><span>Note</span></div><p class="">
- The definition of how often the <code><a href="#dfn-chargingtimechange" class="internalDFN" data-link-type="dfn"><code>chargingtimechange</code></a></code>,
- <code><a href="#dfn-dischargingtimechange" class="internalDFN" data-link-type="dfn"><code>dischargingtimechange</code></a></code>, and <code><a href="#dfn-levelchange" class="internalDFN" data-link-type="dfn"><code>levelchange</code></a>
- </code> events are fired is left to the implementation.
- </p></div>
- <section id="multiple-batteries" typeof="bibo:Chapter" resource="#multiple-batteries" property="bibo:hasPart">
- <h3 id="h-multiple-batteries" resource="#h-multiple-batteries"><span property="xhv:role" resource="xhv:heading"><span class="secno">6.1 </span>Multiple batteries</span></h3>
- <p>
- If a hosting device contains more than one battery,
- <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> <em class="rfc2119" title="SHOULD">SHOULD</em> expose an unified view of the batteries.
- </p>
- <p>
- The <code>charging</code> attribute <em class="rfc2119" title="MUST">MUST</em> be set to true if at least
- one battery's <code>charging</code> state as described above is true.
- Otherwise, it <em class="rfc2119" title="MUST">MUST</em> be set to false.
- </p>
- <p>
- The <code>chargingTime</code> 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.
- </p>
- <p>
- The <code>dischargingTime</code> 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.
- </p>
- <p>
- The <code>level</code> 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.
- </p>
- </section>
- <section id="event-handlers" typeof="bibo:Chapter" resource="#event-handlers" property="bibo:hasPart">
- <h3 id="h-event-handlers" resource="#h-event-handlers"><span property="xhv:role" resource="xhv:heading"><span class="secno">6.2 </span>Event handlers</span></h3>
- <p>
- The following are the <a href="#dfn-event-handlers" class="internalDFN" data-link-type="dfn">event handlers</a> (and their corresponding
- <a href="#dfn-event-handler-event-types" class="internalDFN" data-link-type="dfn">event handler event types</a>) that <em class="rfc2119" title="MUST">MUST</em> be supported as
- attributes by the <a href="#idl-def-BatteryManager" class="idlType"><code>BatteryManager</code></a> object:
- </p>
- <table class="simple">
- <thead>
- <tr>
- <th>event handler</th>
- <th>event handler event type</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onchargingchange">
- onchargingchange
- </code></strong>
- </td>
- <td>
- <code><dfn data-dfn-type="dfn" id="dfn-chargingchange">
- chargingchange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onchargingtimechange">
- onchargingtimechange
- </code></strong>
- </td>
- <td>
- <code><dfn data-dfn-type="dfn" id="dfn-chargingtimechange">
- chargingtimechange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-ondischargingtimechange">
- ondischargingtimechange
- </code></strong>
- </td>
- <td>
- <code><dfn data-dfn-type="dfn" id="dfn-dischargingtimechange">
- dischargingtimechange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onlevelchange">
- onlevelchange
- </code></strong>
- </td>
- <td>
- <code><dfn data-dfn-type="dfn" id="dfn-levelchange">
- levelchange
- </dfn></code>
- </td>
- </tr>
- </tbody>
- </table>
- </section>
- </section>
-
- <section class="informative" id="examples" typeof="bibo:Chapter" resource="#examples" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-examples" resource="#h-examples"><span property="xhv:role" resource="xhv:heading"><span class="secno">7. </span>Examples</span></h2><p><em>This section is non-normative.</em></p>
- <p>
- This trivial example writes the battery level to the console each time
- the level changes:
- </p>
- <div class="example"><div class="example-title"><span>Example 1</span></div><pre class="example highlight prettyprint prettyprinted"><span class="com">// We get the initial value when the promise resolves ...</span><span class="pln">
-navigator</span><span class="pun">.</span><span class="pln">getBattery</span><span class="pun">().</span><span class="kwd">then</span><span class="pun">(</span><span class="kwd">function</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">.</span><span class="pln">level</span><span class="pun">);</span><span class="pln">
- </span><span class="com">// ... and any subsequent updates.</span><span class="pln">
- battery</span><span class="pun">.</span><span class="pln">onlevelchange </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="kwd">this</span><span class="pun">.</span><span class="pln">level</span><span class="pun">);</span><span class="pln">
- </span><span class="pun">};</span><span class="pln">
-</span><span class="pun">});</span></pre></div>
- <p>
- Alternatively, the same using the <code>addEventListener()</code>
- method:
- </p>
- <div class="example"><div class="example-title"><span>Example 2</span></div><pre class="example highlight prettyprint prettyprinted"><span class="pln">navigator</span><span class="pun">.</span><span class="pln">getBattery</span><span class="pun">().</span><span class="kwd">then</span><span class="pun">(</span><span class="kwd">function</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">.</span><span class="pln">level</span><span class="pun">);</span><span class="pln">
- battery</span><span class="pun">.</span><span class="pln">addEventListener</span><span class="pun">(</span><span class="str">'levelchange'</span><span class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- console</span><span class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="kwd">this</span><span class="pun">.</span><span class="pln">level</span><span class="pun">);</span><span class="pln">
- </span><span class="pun">});</span><span class="pln">
-</span><span class="pun">});</span></pre></div>
- <p>
- The following example updates the indicators to show the charging
- state, level and time remaining in minutes:
- </p>
- <div class="example"><div class="example-title"><span>Example 3</span></div><pre class="example highlight prettyprint prettyprinted"><span class="dec"><!DOCTYPE html></span><span class="pln">
-</span><span class="tag"><html></span><span class="pln">
-</span><span class="tag"><head></span><span class="pln">
- </span><span class="tag"><title></span><span class="pln">Battery Status API Example</span><span class="tag"></title></span><span class="pln">
- </span><span class="tag"><script></span><span class="pln">
- window</span><span class="pun">.</span><span class="pln">onload </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="kwd">function</span><span class="pln"> updateBatteryStatus</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- document</span><span class="pun">.</span><span class="pln">querySelector</span><span class="pun">(</span><span class="str">'#charging'</span><span class="pun">).</span><span class="pln">textContent </span><span class="pun">=</span><span class="pln"> battery</span><span class="pun">.</span><span class="pln">charging </span><span class="pun">?</span><span class="pln"> </span><span class="str">'charging'</span><span class="pln"> </span><span class="pun">:</span><span class="pln"> </span><span class="str">'not charging'</span><span class="pun">;</span><span class="pln">
- document</span><span class="pun">.</span><span class="pln">querySelector</span><span class="pun">(</span><span class="str">'#level'</span><span class="pun">).</span><span class="pln">textContent </span><span class="pun">=</span><span class="pln"> battery</span><span class="pun">.</span><span class="pln">level</span><span class="pun">;</span><span class="pln">
- document</span><span class="pun">.</span><span class="pln">querySelector</span><span class="pun">(</span><span class="str">'#dischargingTime'</span><span class="pun">).</span><span class="pln">textContent </span><span class="pun">=</span><span class="pln"> battery</span><span class="pun">.</span><span class="pln">dischargingTime </span><span class="pun">/</span><span class="pln"> </span><span class="lit">60</span><span class="pun">;</span><span class="pln">
- </span><span class="pun">}</span><span class="pln">
-
- navigator</span><span class="pun">.</span><span class="pln">getBattery</span><span class="pun">().</span><span class="pln">then</span><span class="pun">(</span><span class="kwd">function</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// Update the battery status initially when the promise resolves ...</span><span class="pln">
- updateBatteryStatus</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">);</span><span class="pln">
-
- </span><span class="com">// .. and for any subsequent updates.</span><span class="pln">
- battery</span><span class="pun">.</span><span class="pln">onchargingchange </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- updateBatteryStatus</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">);</span><span class="pln">
- </span><span class="pun">};</span><span class="pln">
-
- battery</span><span class="pun">.</span><span class="pln">onlevelchange </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- updateBatteryStatus</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">);</span><span class="pln">
- </span><span class="pun">};</span><span class="pln">
-
- battery</span><span class="pun">.</span><span class="pln">ondischargingtimechange </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- updateBatteryStatus</span><span class="pun">(</span><span class="pln">battery</span><span class="pun">);</span><span class="pln">
- </span><span class="pun">};</span><span class="pln">
- </span><span class="pun">});</span><span class="pln">
- </span><span class="pun">};</span><span class="pln">
- </span><span class="tag"></script></span><span class="pln">
-</span><span class="tag"></head></span><span class="pln">
-</span><span class="tag"><body></span><span class="pln">
- </span><span class="tag"><div</span><span class="pln"> </span><span class="atn">id</span><span class="pun">=</span><span class="atv">"charging"</span><span class="tag">></span><span class="pln">(charging state unknown)</span><span class="tag"></div></span><span class="pln">
- </span><span class="tag"><div</span><span class="pln"> </span><span class="atn">id</span><span class="pun">=</span><span class="atv">"level"</span><span class="tag">></span><span class="pln">(battery level unknown)</span><span class="tag"></div></span><span class="pln">
- </span><span class="tag"><div</span><span class="pln"> </span><span class="atn">id</span><span class="pun">=</span><span class="atv">"dischargingTime"</span><span class="tag">></span><span class="pln">(discharging time unknown)</span><span class="tag"></div></span><span class="pln">
-</span><span class="tag"></body></span><span class="pln">
-</span><span class="tag"></html></span></pre></div>
- </section>
- <section class="appendix" id="acknowledgements" typeof="bibo:Chapter" resource="#acknowledgements" property="bibo:hasPart">
- <!--OddPage--><h2 id="h-acknowledgements" resource="#h-acknowledgements"><span property="xhv:role" resource="xhv:heading"><span class="secno">A. </span>Acknowledgements</span></h2>
- <p>
- The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and
- the Mozilla WebAPI team in general for their invaluable feedback
- based on prototype implementations. Many thanks to the people behind
- the System Information API and Device Orientation Event specification
- for the initial inspiration. Also thanks to the nice folks bringing us
- the Page Visibility specification, which motivated the editor of this
- specification to write the introduction chapter discussing some
- real-world high value use cases that apply equally to this
- specification. Special thanks to all the participants of the Device
- APIs Working Group and others who have sent in substantial feedback
- and comments, and made the Web a better place for everyone by
- doing so. Finally, thanks to Lukasz Olejnik, Gunes Acar, Claude
- Castelluccia, and Claudia Diaz for the privacy analysis of the API.
- </p>
- </section>
-
-
-<section id="references" class="appendix" typeof="bibo:Chapter" resource="#references" property="bibo:hasPart"><!--OddPage--><h2 id="h-references" resource="#h-references"><span property="xhv:role" resource="xhv:heading"><span class="secno">B. </span>References</span></h2><section id="normative-references" typeof="bibo:Chapter" resource="#normative-references" property="bibo:hasPart"><h3 id="h-normative-references" resource="#h-normative-references"><span property="xhv:role" resource="xhv:heading"><span class="secno">B.1 </span>Normative references</span></h3><dl class="bibliography" resource=""><dt id="bib-ECMASCRIPT">[ECMASCRIPT]</dt><dd>Allen Wirfs-Brock. <a href="http://www.ecma-international.org/ecma-262/6.0/" property="dc:requires"><cite>ECMA-262 6th Edition, The ECMAScript 2015 Language Specification</cite></a>. June 2015. Standard. URL: <a href="http://www.ecma-international.org/ecma-262/6.0/" property="dc:requires">http://www.ecma-international.org/ecma-262/6.0/</a>
-</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. <a href="http://www.w3.org/TR/html5/" property="dc:requires"><cite>HTML5</cite></a>. 28 October 2014. W3C Recommendation. URL: <a href="http://www.w3.org/TR/html5/" property="dc:requires">http://www.w3.org/TR/html5/</a>
-</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="https://tools.ietf.org/html/rfc2119" property="dc:requires"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://tools.ietf.org/html/rfc2119" property="dc:requires">https://tools.ietf.org/html/rfc2119</a>
-</dd><dt id="bib-WEBIDL">[WEBIDL]</dt><dd>Cameron McCormack; Boris Zbarsky. <a href="http://www.w3.org/TR/WebIDL-1/" property="dc:requires"><cite>WebIDL Level 1</cite></a>. 4 August 2015. W3C Working Draft. URL: <a href="http://www.w3.org/TR/WebIDL-1/" property="dc:requires">http://www.w3.org/TR/WebIDL-1/</a>
-</dd></dl></section></section></body></html>
\ No newline at end of file
+ </head>
+ <body>
+ Moved to <a href="https://w3c.github.io/battery/">
+ https://w3c.github.io/battery/</a>
+ </body>
+</html>
--- a/battery/Overview.src.html Thu Aug 20 15:50:38 2015 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,498 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <title>Battery Status API</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
- <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
- <script class="remove">
- var respecConfig = {
- specStatus: "ED",
- shortName: "battery-status",
- // publishDate: "2014-12-09",
- previousPublishDate: "2014-12-09",
- previousMaturity: "CR",
- edDraftURI: "https://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html",
- // crEnd: "2015-02-03",
- editors: [
- { name: "Anssi Kostiainen", company: "Intel", companyURL: "http://intel.com/" },
- { name: "Mounir Lamouri", company: "Google Inc.", companyURL: "http://google.com/", note: "previously Mozilla" }
- ],
- inlineCSS: true,
- noIDLIn: true,
- noLegacyStyle: true,
- wg: "Device APIs Working Group",
- wgURI: "http://www.w3.org/2009/dap/",
- wgPublicList: "public-device-apis",
- wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
- testSuiteURI: "http://w3c-test.org/battery-status/",
- implementationReportURI: "http://www.w3.org/2009/dap/wiki/ImplementationStatus",
- scheme: "https",
- processVersion: 2005
- };
- </script>
- </head>
- <body>
- <section id="abstract">
- 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
- specified as part of the
- <a href="http://www.w3.org/TR/system-info-api/">System Information
- API</a> but has been extracted in order to be more readily available,
- more straightforward to implement, and in order to produce a
- specification that could be implemented on its own merits without
- interference with other, often unrelated, features.
- </p>
- <p>
- No substantial changes have been made since the
- <a href="http://www.w3.org/TR/2014/WD-battery-status-20140828/">
- W3C Last Call Working Draft 28 August 2014</a>
- (<a href="CR2-diff.html">diff</a>).
- </p>
- <p>
- The CR exit criterion is two interoperable deployed implementations of
- each feature. No features are marked as 'at-risk'.
- </p>
- </section>
-
- <section class="informative">
- <h2>Introduction</h2>
- <p>
- The Battery Status API specification defines a means for web
- developers to programmatically determine the battery status of the
- hosting device. Without knowing the battery status of a device, a web
- developer must design the web application with an assumption of
- sufficient battery level for the task at hand. This means the battery
- of a device may exhaust faster than desired because web developers are
- unable to make decisions based on the battery status. Given knowledge
- of the battery status, web developers are able to craft web content and
- applications which are power-efficient, thereby leading to improved
- user experience. Authors should be aware, however, that a naïve
- implementation of this API can negatively affect the battery life.
- </p>
- <p>
- The Battery Status API can be used to defer or scale back work when
- the device is not charging in or is low on battery. An archetype of an
- advanced web application, a web-based email client, may check the
- server for new email every few seconds if the device is charging,
- but do so less frequently if the device is not charging or is low on
- battery. Another example is a web-based word processor which could
- monitor the battery level and save changes before the battery runs
- out to prevent data loss.
- </p>
- </section>
-
- <section id="conformance">
- <p>
- This specification defines conformance criteria that apply to a single
- product: the <dfn>user agent</dfn> that implements the
- interfaces that it contains.
- </p>
- <p>
- Implementations that use ECMAScript to implement the APIs defined in
- this specification must implement them in a manner consistent with the
- ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]],
- as this specification uses that specification and terminology.
- </p>
- </section>
- <section>
- <h2>Terminology</h2>
- <p>
- The following concepts, terms and interfaces are defined in [[!HTML5]]:
- </p>
- <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></dfn></li>
- <li><dfn><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
- browsing context</a></dfn></li>
- </ul>
- <p>
- <a href=
- 'http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects'>
- <dfn>Promise</dfn></a> objects are defined in [[!ECMASCRIPT]].
- </p>
- </section>
- <section class="informative">
- <h2>Security and privacy considerations</h2>
- <p>
- The API defined in this specification is used to determine the battery
- status of the hosting device.
- </p>
- <p>
- The user agent SHOULD not expose high precision readouts of battery
- status information as that can introduce a new fingerprinting vector.
- </p>
- <p>
- The user agent MAY ask the user for battery status information access, or
- alternatively, enforce the user permission requirement in its private
- browsing modes.
- </p>
- <p>
- The user agent SHOULD inform the user of the API use by scripts in an
- unobtrusive manner to aid transparency and to allow the user to revoke
- the API access.
- </p>
- <p>
- The user agent MAY 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>The <a>Navigator</a> interface</h2>
- <dl title="partial interface Navigator" class="idl">
- <dt>Promise<BatteryManager> getBattery()</dt>
- <dd></dd>
- </dl>
- <p>
- For each <a>browsing context</a>, there is a <dfn>battery promise</dfn>,
- which is initially set to <code>null</code>. It is a <a>Promise</a>
- object which holds a <a>BatteryManager</a>.
- </p>
- <p>
- The <code id="widl-Navigator-getBattery-Promise-BatteryManager">getBattery()</code>
- method, when invoked, MUST run the following steps:
- </p>
- <ul>
- <li>
- If <a>battery promise</a> is not <code>null</code>, return <a>battery
- promise</a> and abort these steps.
- </li>
- <li>
- Otherwise, set <a>battery promise</a> to a newly created
- <a>Promise</a>.
- </li>
- <li>
- Return <a>battery promise</a> and continue asynchronously.
- </li>
- <li>
- <a>Create a new <code>BatteryManager</code> object</a>,
- and let <var>battery</var> be that object.
- </li>
- <li>
- <dfn>Resolve</dfn> <a>battery promise</a> with <var>battery</var>.
- </li>
- </ul>
- <p>
- The <a>user agent</a> MUST NOT reject the <a>battery promise</a>.
- </p>
- </section>
-
- <section>
- <h2>The <a>BatteryManager</a> interface</h2>
- <p>
- The <a>BatteryManager</a> interface represents the <dfn>current battery
- status information</dfn> of the hosting device. The <code>charging</code>
- attribute represents the charging state of the system's battery.
- The <code>chargingTime</code> attribute represents the time remaining
- in seconds until the system's battery is fully charged. The
- <code>dischargingTime</code> 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 <code>level</code> attribute
- represents the level of the system's battery.
- </p>
- <dl title="interface BatteryManager : EventTarget"
- class="idl">
- <dt>readonly attribute boolean charging</dt>
- <dd></dd>
- <dt>readonly attribute unrestricted double chargingTime</dt>
- <dd></dd>
- <dt>readonly attribute unrestricted double dischargingTime</dt>
- <dd></dd>
- <dt>readonly attribute double level</dt>
- <dd></dd>
- <dt>
- attribute EventHandler onchargingchange
- </dt>
- <dd></dd>
- <dt>
- attribute EventHandler onchargingtimechange
- </dt>
- <dd></dd>
- <dt>
- attribute EventHandler ondischargingtimechange
- </dt>
- <dd></dd>
- <dt>
- attribute EventHandler onlevelchange
- </dt>
- <dd></dd>
- </dl>
- <p>
- When the <a>user agent</a> is to <dfn>create a new
- <code>BatteryManager</code> object</dfn>, it MUST instantiate a new
- <a>BatteryManager</a> object and set its attributes' values to those
- that represent the <a>current battery status information</a>, unless
- the <a>user agent</a> is <a>unable to report the battery status
- information</a>, in which case the values MUST be set to <dfn>default
- values</dfn> as follows:
- <code>charging</code> MUST be set to true,
- <code>chargingTime</code> MUST be set to 0,
- <code>dischargingTime</code> MUST be set to positive Infinity, and
- <code>level</code> MUST be set to 1.0.
- </p>
- <p>
- The <a>user agent</a> is said to be <dfn>unable to report the
- battery status information</dfn>, 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.
- </p>
- <p class="note">
- Implementations <a>unable to report the battery status information</a>
- 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.
- </p>
- <p>
- The <code id="widl-BatteryManager-charging">charging</code>
- 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 <a>user agent</a> MUST <a>queue a task</a> which sets
- the <code>charging</code> attribute's value and <a>fires a simple
- event</a> named <code><a>chargingchange</a></code> at the
- <a>BatteryManager</a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-chargingTime">chargingTime</code>
- 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 <a>user
- agent</a> MUST <a>queue a task</a> which sets the
- <code>chargingTime</code> attribute's value and <a>fires a simple
- event</a> named <code><a>chargingtimechange</a></code> at the
- <a>BatteryManager</a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-dischargingTime">dischargingTime</code>
- 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 <a>user agent</a> MUST <a>queue a task</a> which sets
- the <code>dischargingTime</code> attribute's value and <a>fires a
- simple event </a> named <code><a>dischargingtimechange</a></code> at the
- <a>BatteryManager</a> object.
- </p>
- <p>
- The <code id="widl-BatteryManager-level">level</code>
- 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 <a>user agent</a> MUST <a>queue a
- task</a> which sets the <code>level</code> attribute's value and
- <a>fires a simple event</a> named <code><a>levelchange</a></code> at
- the <a>BatteryManager</a> object.
- </p>
- <p class="note">
- The definition of how often the <code><a>chargingtimechange</a></code>,
- <code><a>dischargingtimechange</a></code>, and <code><a>levelchange</a>
- </code> events are fired is left to the implementation.
- </p>
- <section id="multiple-batteries">
- <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>chargingTime</code> 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.
- </p>
- <p>
- The <code>dischargingTime</code> 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.
- </p>
- <p>
- The <code>level</code> 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.
- </p>
- </section>
- <section>
- <h2>Event handlers</h2>
- <p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>BatteryManager</a> object:
- </p>
- <table class="simple">
- <thead>
- <tr>
- <th>event handler</th>
- <th>event handler event type</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onchargingchange">
- onchargingchange
- </code></strong>
- </td>
- <td>
- <code><dfn>
- chargingchange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onchargingtimechange">
- onchargingtimechange
- </code></strong>
- </td>
- <td>
- <code><dfn>
- chargingtimechange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-ondischargingtimechange">
- ondischargingtimechange
- </code></strong>
- </td>
- <td>
- <code><dfn>
- dischargingtimechange
- </dfn></code>
- </td>
- </tr>
- <tr>
- <td>
- <strong><code id="widl-BatteryManager-onlevelchange">
- onlevelchange
- </code></strong>
- </td>
- <td>
- <code><dfn>
- levelchange
- </dfn></code>
- </td>
- </tr>
- </tbody>
- </table>
- </section>
- </section>
-
- <section class="informative">
- <h2>Examples</h2>
- <p>
- This trivial example writes the battery level to the console each time
- the level changes:
- </p>
- <pre class="example highlight">
- // We get the initial value when the promise resolves ...
- navigator.getBattery().then(function(battery) {
- console.log(battery.level);
- // ... and any subsequent updates.
- battery.onlevelchange = function() {
- console.log(this.level);
- };
- });
- </pre>
- <p>
- Alternatively, the same using the <code>addEventListener()</code>
- method:
- </p>
- <pre class="example highlight">
- navigator.getBattery().then(function(battery) {
- console.log(battery.level);
- battery.addEventListener('levelchange', function() {
- console.log(this.level);
- });
- });
- </pre>
- <p>
- The following example updates the indicators to show the charging
- state, level and time remaining in minutes:
- </p>
- <pre class="example highlight">
- <!DOCTYPE html>
- <html>
- <head>
- <title>Battery Status API Example</title>
- <script>
- window.onload = function () {
- function updateBatteryStatus(battery) {
- document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
- document.querySelector('#level').textContent = battery.level;
- document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
- }
-
- navigator.getBattery().then(function(battery) {
- // Update the battery status initially when the promise resolves ...
- updateBatteryStatus(battery);
-
- // .. and for any subsequent updates.
- battery.onchargingchange = function () {
- updateBatteryStatus(battery);
- };
-
- battery.onlevelchange = function () {
- updateBatteryStatus(battery);
- };
-
- battery.ondischargingtimechange = function () {
- updateBatteryStatus(battery);
- };
- });
- };
- </script>
- </head>
- <body>
- <div id="charging">(charging state unknown)</div>
- <div id="level">(battery level unknown)</div>
- <div id="dischargingTime">(discharging time unknown)</div>
- </body>
- </html>
- </pre>
- </section>
- <section class="appendix">
- <h2>Acknowledgements</h2>
- <p>
- The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and
- the Mozilla WebAPI team in general for their invaluable feedback
- based on prototype implementations. Many thanks to the people behind
- the System Information API and Device Orientation Event specification
- for the initial inspiration. Also thanks to the nice folks bringing us
- the Page Visibility specification, which motivated the editor of this
- specification to write the introduction chapter discussing some
- real-world high value use cases that apply equally to this
- specification. Special thanks to all the participants of the Device
- APIs Working Group and others who have sent in substantial feedback
- and comments, and made the Web a better place for everyone by
- doing so. Finally, thanks to Lukasz Olejnik, Gunes Acar, Claude
- Castelluccia, and Claudia Diaz for the privacy analysis of the API.
- </p>
- </section>
- </body>
-</html>