W3C

The Network Information API

W3C Working Draft 07 June 2011

This version:
http://www.w3.org/TR/2011/WD-netinfo-api-20110607/
Latest published version:
http://www.w3.org/TR/netinfo-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/netinfo/
Editors:
Suresh Chitturi, Research In Motion (RIM)
Robin Berjon, Robineko

Abstract

The Network Information API provides an interface for Web Applications to access the underlying network information (connection info) of the device.

Status of This Document

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.

Table of Contents

1. Conformance

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].

2. Introduction

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;

3. API Description

3.1 The 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;
};

3.1.1 Attributes

connection of type Connection, readonly
The object from which connection information is accessed.
No exceptions.

3.2 The Connection interface

The Connection interface provides a handle to the device's connection information.

[NoInterfaceObject]
interface Connection {
    readonly attribute DOMString type;
};

3.2.1 Attributes

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?

No exceptions.

4. Changes in connection information

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.

A. Acknowledgements

TBD

B. References

B.1 Normative references

[HTML5]
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

B.2 Informative references

No informative references.