Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
The functionality described in this specification was initially specified as part of the System Information API 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.
This document was published by the Device APIs and Policy Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C 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.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures 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 Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
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.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
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].
This section is non-normative.
The Network Information API provides an interface enabling Web applications to access the underlying network information (connection type) of the device.
// add a class on the root list that matches a specific connection type function updateConnectionClass () { var root = document.documentElement, types = "unknown ethernet wifi 2g 3g 4g none".split(" "); for (var i = 0, n = types.length; i < n; i++) root.classList.remove("network-" + types[i]) root.classList.add("network-" + navigator.connection.type); } window.onload = window.ononline = window.onoffline = updateConnectionClass;
NetworkInfo
interface
The NetworkInfo
interface is exposed on the
Navigator
object.
Navigator implements NetworkInfo
;
All instances of the Navigator
type are defined to also implement the NetworkInfo
interface.
[NoInterfaceObject]
interface NetworkInfo {
readonly attribute Connection
connection;
};
connection
of type Connection
, readonlyConnection
interface
The Connection
interface provides a handle to the device's connection information.
[NoInterfaceObject]
interface Connection {
readonly attribute DOMString type;
};
type
of type DOMString, readonly
Exposes the current connection type. The value returned is one of the following strings,
case-sensitively: unknown
, ethernet
, wifi
, 2g
,
3g
, 4g
, none
. Implementers may expose other values,
in which case it is recommended that they are prefixed with a vendor-specific identifier, e.g.
acme-superluminal
. Other identifiers may be added in the future.
The existing implementation, Android, uses integer constants for this (which is a shame since other parts of the Android platform use the more reasonable strings instead). Should we just go with it?
When changes in the underlying device's connection information occur, the user agent must
queue a task to fire a simple event named
either online
or offline
depending on the applicable value, as defined
in [HTML5].
Note that this may cause the same event (online
or offline
) to be triggered
multiple times in succession rather than toggling between either value.
There is discussion about whether this justifies a new event or not. People may have some initialisation
code that runs on online
which they don't expect to have to run when one switches from
Wi-Fi to ethernet. By its very nature, such code should be able to run multiple times with no harm, but
it may still be wasteful to do so.
TBD
No informative references.