W3C home > Mailing lists > Public > public-dap-commits@w3.org > January 2012

dap commit: Network Information API new version, editor draft

From: Mercurial notifier <cvsmail@w3.org>
Date: Tue, 31 Jan 2012 17:04:30 +0000
Message-Id: <E1RsH8A-00013m-Vn@mcbain.w3.org>
To: public-dap-commits@w3.org
changeset:   46:84a2fb7b753b
tag:         tip
user:        Mounir Lamouri <mounir.lamouri@gmail.com>
date:        Tue Jan 31 18:00:31 2012 +0100
files:       network-api/index.html
description:
Network Information API new version, editor draft


diff -r 5c5b22705789 -r 84a2fb7b753b network-api/index.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/network-api/index.html	Tue Jan 31 18:00:31 2012 +0100
@@ -0,0 +1,287 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>The Network Information API</title>
+    <meta http-equiv='Content-Type' content='text/html;charset=utf-8' />
+
+<!--
+    <script src='../ReSpec.js/js/respec.js' class='remove'></script>
+-->
+    <script src='http://respec.specifiction.com/js/profiles/w3c-common.js' class='remove'></script>
+    <script class='remove'>
+      var respecConfig = {
+          specStatus:           "ED",
+          shortName:            "netinfo-api",
+
+          //publishDate:  "2012-12-12",
+          previousPublishDate:  "2011-06-07",
+          previousMaturity:     "ED",
+          edDraftURI:           "TBD",
+
+          // if this is a LCWD, uncomment and set the end of its review period
+          // lcEnd: "2009-08-05",
+          extraCSS:             ["../ReSpec.js/css/respec.css"],
+          noIDLIn:    true,
+
+          editors:  [
+              { name: "Mounir Lamouri",
+                company: "Mozilla",
+                companyURL: "http://mozilla.org/" },
+          ],
+          wg:           "Device APIs and Policy Working Group",
+          wgURI:        "http://www.w3.org/2009/dap/",
+          wgPublicList: "public-device-apis",
+          wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status"
+      };
+    </script>
+  </head>
+
+  <body>
+    <section id='abstract'>
+      The Network Information API provides an interface for Web Applications to
+      access the underlying connection information of the 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>
+    </section>
+
+    <section class="informative">
+      <h2>Introduction</h2>
+      <p>
+        The Network Information API provides an interface enabling Web applications to access the underlying
+        connection information of the device.
+      </p>
+      <p>
+        The following example shows how an image viewer can select a low definition or a high definition image based on the
+        current connection bandwidth:
+      <pre class="example sh_javascript">
+        &lt;!DOCTYPE&gt;
+        &lt;html&gt;
+          &lt;head&gt;
+            &lt;title&gt;Poney viewer&lt;/title&gt;
+          &lt;/head&gt;
+          &lt;body&gt;
+            &lt;img id='poney' alt="An image showing a poney" title="My precious!"&gt;&lt;/img&gt;
+            &lt;script&gt;
+              var i = document.getElementById('poney');
+
+              if (navigator.connection.bandwidth > 2) {
+                i.src = "http://example.com/poney_hd.png";
+              } else {
+                i.src = "http://example.com/poney_ld.png";
+              }
+            &lt;/script&gt;
+          &lt;/body&gt;
+        &lt;/html&gt;
+      </pre>
+    </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 expose the APIs defined in this specification must implement them in a manner
+        consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].
+      </p>
+    </section>
+
+    <section>
+      <h2>Terminology</h2>
+      <p>
+        The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#function">
+        Function</a></code> interface represents a function in the scripting
+        language being used as defined in [[!HTML5]].
+      </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]].
+      </p>
+    </section>
+
+    <section>
+      <h2>Security and privacy considerations</h2>
+      <p>
+        The API defined in this specification is used to determine the connection information
+        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 what kind of connection
+        is actually in use by the hosting device.
+      </p>
+    </section>
+
+    <section>
+      <h2>The <a>NetworkInformation</a> interface</h2>
+      <p>
+        The <a>NetworkInformation</a> interface is exposed on the 
+        <code>Navigator</code> object.
+      </p>
+      <div class='idl' title='Navigator implements NetworkInformation'></div>
+      <dl title='[NoInterfaceObject] interface NetworkInformation' class='idl'>
+        <dt>readonly attribute Connection connection</dt>
+        <dd>
+          The object from which connection information is accessed.
+        </dd>
+      </dl>
+    </section>
+
+    <section>
+      <h2>The <a>Connection</a> interface</h2>
+      <p>
+        The <a>Connection</a> interface provides a handle to the device's connection information.
+      </p>
+      <dl title='[NoInterfaceObject]
+                 interface Connection : EventTarget' class='idl'>
+        <dt>readonly attribute double  bandwidth</dt>
+        <dd>
+          The attribute SHOULD return an estimation of the current bandwdith in MB/s (Megabytes per seconds) the <a>user agent</a>
+          has with the Document's subdomain. It MUST return Infinity if the bandwidth is unknown and it MUST return 0 if the user
+          is currently offline.
+        </dd>
+        <dt>readonly attribute boolean metered</dt>
+        <dd>
+          <p>
+            A connection is <dfn>metered</dfn> when the user's connection is subject to a limitation from his Internet Service Provider
+            strong enough to request web applications to be gentle with the bandwidth usage.
+          </p>
+          <div class="note">
+            What is a metered connection is voluntarily left to the <a>user agent</a>. It would not be possible to give an exhaustive
+            way of all limitations considered strong enough to flag the connection has metered and even if doable, some limitations can be
+            considered strong or weak depending on the context.<br>
+            Examples of metered connections are mobile connection with a small bandwidth quota or a connection with a pay-per use.
+          </div>
+          <p>
+            The attribute SHOULD return true if the connection with the Document's subdomain is <a title='metered'>metered</a> and false otherwise.
+            If the implementation is not able to know the status of the connection or if the user is offline, it MUST return false.
+          </p>
+          <div class="note">
+            If not able to know if a connection is metered, a <a>user agent</a> could ask the user about the status of his current connection. For example, a preference letting the user say if the mobile connection used on the device is metered.
+          </div>
+        </dd>
+        <dt>[TreatNonCallableAsNull] attribute Function? onchange</dt>
+        <dd></dd>
+      </dl>
+
+      <p>
+        When the <code>Connection</code> changes, the <a>user agent</a> MUST <a>queue a task</a> which updates
+        the <code>Connection</code> properties and <a>fires a simple event</a> named <code>change</code> at the
+        <code>Connection</code> object.
+      </p>
+
+      <p>
+        When the user goes online or offline, in addition of the <code>change</code> event fired on the <code>Connection</code>
+        object, the <a>user agent</a> has to <a>fire a simple event</a> named either <code>online</code> or <code>offline</code>
+        depending on the applicable value, as defined in [[!HTML5]].
+      </p>
+
+      <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 <code>Connection</code> object:
+        </p>
+
+        <table class="simple">
+          <thead>
+            <tr>
+              <th>event handler</th>
+              <th>event handler event type</th>
+            </tr>
+          </thead>
+          <tbody>
+
+            <tr>
+              <td><strong><code>onchange</code></strong></td>
+              <td><code>change</code></td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+    </section>
+
+    <section class='informative'>
+      <h2>Examples</h2>
+      <p>
+        This trivial example writes the connection bandwidth to the console and shows it again each time it is changing:
+      </p>
+      <div class="example">
+        <pre class="example sh_javascript">
+          function show() {
+            console.log(navigator.connection.bandwidth);
+          }
+
+          navigator.connection.addEventListener('change', show, false);
+
+          show();
+        </pre>
+      </div>
+
+      <p>
+        This example shows how an application can prevent automatic polling using the metered attribute:
+      </p>
+      <div class="example">
+        <pre class="example sh_javascript">
+          &lt;!DOCTYPE html&gt;
+          &lt;html&gt;
+            &lt;head&gt;
+              &lt;title&gt;Conditional polling&lt;/title&gt;
+              &lt;script&gt;
+                var gPreviousMetered = navigator.connection.metered;
+                var gIntervalId;
+
+                function poll() {
+                  // poll stuff
+                }
+
+                navigator.connection.addEventListener('change', function() {
+                  if (gPreviousMetered == navigator.connection.metered) {
+                    return;
+                  }
+
+                  gPreviousMetered = navigator.connection.metered;
+                  if (navigator.connection.metered) {
+                    gIntervalId = setInterval(poll, 1000);
+                  } else {
+                    clearInterval(gIntervalId);
+                  }
+                }, false);
+
+                // At load time.
+                if (navigator.connection.metered) {
+                  gIntervalId = setInterval(poll, 1000);
+                }
+              &lt;/script&gt;
+            &lt;/head&gt;
+            &lt;body&gt;
+              &lt;button onclick="poll();"&gt;Poll&lt;/button&gt;
+            &lt;/body&gt;
+          &lt;/html&gt;
+        </pre>
+      </div>
+    </section>
+
+    <section class='appendix'>
+      <h2>Acknowledgements</h2>
+      <p>
+      </p>
+    </section>
+  </body>
+</html>
Received on Tuesday, 31 January 2012 17:04:33 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 31 January 2012 17:04:34 GMT