--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/network-api/Overview.html Mon May 21 16:15:41 2012 +0200
@@ -0,0 +1,307 @@
+<!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 highlight">
+ <!DOCTYPE>
+ <html>
+ <head>
+ <title>Poney viewer</title>
+ </head>
+ <body>
+ <img id='poney' alt="An image showing a poney" title="My precious!">
+ <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">
+ fire 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>
+
+ <p>
+ The concepts of <dfn><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
+ browsing context</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/browsers.html#active-document">
+ active document</a></dfn> are defined in [[!HTML5]].
+ </p>
+
+ <p>
+ The concept of document <dfn><a href="http://dev.w3.org/html5/spec/origin-0.html#the-document-s-domain">
+ domain</a></dfn> is 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 <a>user agent</a> MUST set the value of the <code>bandwidth</code> attribute to:
+ <ul>
+ <li>0 if the user is currently offline;</li>
+ <li>Infinity if the bandwidth is unknown;</li>
+ <li>an estimation of the current bandwidth in MB/s (Megabytes per seconds) available for communication with the
+ <a>browsing context</a> <a>active document</a>'s <a>domain</a>.
+ </li>
+ </ul>
+ </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 careful with the bandwidth usage.
+ </p>
+ <div class="note">
+ What is a metered connection is voluntarily left to the <a>user agent</a> to judge. It would not be possible to give an exhaustive
+ list of limitations considered strong enough to flag the connection as metered and even if doable, some limitations can be
+ considered strong or weak depending on the context.<br>
+ Examples of metered connections are mobile connections with a small bandwidth quota or connections with a pay-per use plan.
+ </div>
+ <p>
+ The <a>user agent</a> MUST set the value of the <code>metered</code> attribute to true if the connection with the
+ <a>browsing context</a> <a>active document</a>'s <a>domain</a> 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, the value MUST be set to false.
+ </p>
+ <div class="note">
+ If unnable 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 could let the user define 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>fire 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 to 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 highlight">
+ 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 highlight">
+ <!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>
+ Special thanks to Robin Berjon for his help.
+ </p>
+ </section>
+ </body>
+</html>
--- a/network-api/index.html Mon May 21 12:30:05 2012 +0300
+++ b/network-api/index.html Mon May 21 16:15:41 2012 +0200
@@ -2,306 +2,9 @@
<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 highlight">
- <!DOCTYPE>
- <html>
- <head>
- <title>Poney viewer</title>
- </head>
- <body>
- <img id='poney' alt="An image showing a poney" title="My precious!">
- <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">
- fire 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>
-
- <p>
- The concepts of <dfn><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
- browsing context</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/browsers.html#active-document">
- active document</a></dfn> are defined in [[!HTML5]].
- </p>
-
- <p>
- The concept of document <dfn><a href="http://dev.w3.org/html5/spec/origin-0.html#the-document-s-domain">
- domain</a></dfn> is 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 <a>user agent</a> MUST set the value of the <code>bandwidth</code> attribute to:
- <ul>
- <li>0 if the user is currently offline;</li>
- <li>Infinity if the bandwidth is unknown;</li>
- <li>an estimation of the current bandwidth in MB/s (Megabytes per seconds) available for communication with the
- <a>browsing context</a> <a>active document</a>'s <a>domain</a>.
- </li>
- </ul>
- </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 careful with the bandwidth usage.
- </p>
- <div class="note">
- What is a metered connection is voluntarily left to the <a>user agent</a> to judge. It would not be possible to give an exhaustive
- list of limitations considered strong enough to flag the connection as metered and even if doable, some limitations can be
- considered strong or weak depending on the context.<br>
- Examples of metered connections are mobile connections with a small bandwidth quota or connections with a pay-per use plan.
- </div>
- <p>
- The <a>user agent</a> MUST set the value of the <code>metered</code> attribute to true if the connection with the
- <a>browsing context</a> <a>active document</a>'s <a>domain</a> 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, the value MUST be set to false.
- </p>
- <div class="note">
- If unnable 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 could let the user define 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>fire 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 to 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 highlight">
- 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 highlight">
- <!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>
- Special thanks to Robin Berjon for his help.
- </p>
- </section>
+ Moved to <a href="http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html">
+ http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html</a>
</body>
</html>