Network Information API

## Use cases and requirements This document attempts to address the [requirements](https://github.com/w3c-webmob/netinfo/blob/master/README.md) from the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo) document published by the Web and Mobile Interest Group. Those are: * Provide access to the connection type the system is using to communicate with the network (e.g., cellular, bluetooth, ethernet, wifi, other, or none). This information needs to be available either immediately on page load or as close as possible to it. * Provide a means for scripts to be notified if the connection type changes. This is to allow developers to make dynamic changes to the DOM and/or inform the user that the network connection type has changed (and that it could impact them in some way).

## Examples of usage For examples of the kinds of applications one can build with this API, see the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo).

// Get the connection type.
var type = navigator.connection.type;

// The maximum downlink speed of the connection
var max = navigator.connection.downlinkMax;

function changeHandler(e) {
  // Handle change to connection here.
}

// Register for event changes.
navigator.connection.onchange = changeHandler;

// Alternatively.
navigator.connection.addEventListener('change', changeHandler);

## Connection types This section defines the connection types:

bluetooth: The user agent is using a Bluetooth connection as the underlying connection technology.
cellular: The user agent is using a cellular connection as the underlying connection technology (e.g., EDGE, HSPA, LTE, etc.).
ethernet: The user agent is using an Ethernet connection as the underlying connection technology.
none: The user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail) - i.e., equivalent to `navigator.onLine === false` in HTML.
wifi: The user agent is using a Wi-Fi connection as the underlying connection technology.
wimax: The user agent is using a WiMAX connection as the underlying connection technology.
other: The user agent is using a connection type that is not one of enumerated connection types as the underlying connection technology.
unknown: The user agent has established a network connection, but is unable to determine what is the underlying connection technology.

## The `NetworkInformation` interface The `NetworkInformation` interface provides a means to access information about the network connection the user agent is currently using.

readonly attribute ConnectionType type
readonly attribute Megabit downlinkMax
attribute EventHandler onchange

### `type` attribute The `type` attribute, when getting, returns the connection type that the user agent is using. ### `downlinkMax` attribute The `downlinkMax` attribute represents the maximum downlink speed, in megabits per second (Mbps), for underlying connection technology.

## Underlying connection technology The underlying connection technology represents the generation and/or version of the network connection being used by the device. For example, "HSPA" (3.5G) for cellular, or "802.11g" for Wi-Fi. This differs from the connection type exposed by the API, in that it is more fine grained. Each underlying connection technology has an associated maximum downlink speed, which is the maximum download data rate of the current network interface in megabits per second. The relationship between an underlying connection technology and its maximum downlink speed is determined by the properties of the current network interface (e.g signal strength, modulation algorithm, and other relevant "network weather" variables), or where such interface information is not available, is determined by the standardized, or generally accepted, maximum download data rate captured in the table of maximum downlink speeds.

The underlying connection technology is not directly exposed to script. Instead, the maximum downlink speed is exposed via the `downlinkMax` attribute.

Table of maximum downlink speeds
Connection type	Underlying connection technology	Generation or Version	Max downlink speed (Mbit/s)
Data available as JSON.

### Handling changes to the underlying connection If the underlying connection technology changes (in either connection type or maximum downlink speed), the user agent MUST run the steps to update the connection values: 1. Let new-type be the connection type that represents the underlying connection technology. 1. Let max-value be `+Infinity`. 1. If new-type is "none", set max-value to `0`. 1. Otherwise, if new-type is not "unknown": 1. Set max-value to the maximum downlink speed of the underlying connection technology as determined by the properties of the current network interface, or where such interface information is not available, using the table of maximum downlink speeds. 1. If max-value is not equal to the value of `connection.downlinkMax` or if new-type is not equal to the value of `connection.type`: 1. Using the networking task source, queue a task to perform the following: 1. Set `connection.downlinkMax` to max-value. 1. Set `connection.type` to new-type. 1. Fire a simple event named `change` at the `NetworkInformation` object.

Aug	SEP	Oct
	09
2014	2015	2016