- From: Mercurial notifier <cvsmail@w3.org>
- Date: Tue, 31 Jan 2012 17:04:30 +0000
- 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"> + <!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>
Received on Tuesday, 31 January 2012 17:04:33 UTC