--- /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">
+ <!DOCTYPE>
+ <html>
+ <head>
+ <title>Poney viewer</title>
+ </head>
+ <body>
+ <img id='poney' alt="An image showing a poney" title="My precious!"></img>
+ <script>
+ 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";
+ }
+ </script>
+ </body>
+ </html>
+ </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">
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Conditional polling</title>
+ <script>
+ 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);
+ }
+ </script>
+ </head>
+ <body>
+ <button onclick="poll();">Poll</button>
+ </body>
+ </html>
+ </pre>
+ </div>
+ </section>
+
+ <section class='appendix'>
+ <h2>Acknowledgements</h2>
+ <p>
+ </p>
+ </section>
+ </body>
+</html>