This specification defines an API to provide Web applications with access to various properties of the system which they are running on. Specifically, properties pertaining to the device hardware are addressed. Examples include battery status, current network bandwidth. Additionally, some of those properties offer access to the environment around the device, such as ambient brightness or atmospheric pressure.

This document represents the early consensus of the group on the scope and features of the proposed System Information API. Issues and editors notes in the document highlight some of the points on which the group is still working and would particularly like to get feedback.

Introduction

In order for web applications to gain access to information only available to an operating system's native applications, they must be able to access various data present on the device, either related to the hardware state (e.g. CPU load), software data (e.g. pictures stored) or environment information (e.g. ambient brightness). The APIs defined by the Device APIs and Policy Working Group address this issue. Specifically, the API defined in this specification provides access to hardware devices, either internal (CPU, Thermometers) or ambient (light, noise or temperature).

Security and Privacy Considerations

A Web application using this API has access to device specific data which may contain information that the user considers private. For instance a user may object to a Web application transmitting the device's CPU load to an untrusted server, or letting another application modify the device's screen brightness without the user's consent. Therefore, a conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism SHOULD ensure that no information exposed by this API is retrievable or modifiable without the user's express permission

Privacy considerations for implementors

User Agents MUST NOT retrieve or update system information to Web sites without the express permission of the user. User Agents MUST acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface MUST include the URI of the document origin, as defined in [[!HTML5]]. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context, as defined in [[!HTML5]], is navigated to another URL) MUST be revocable and User Agents MUST respect revoked permissions.

Obtaining the user's express permission to access one API method does not imply the user has granted permission for the same Web site to access other methods provided by this API, or to access the same method with a different set of arguments, as part of the same permission context. If a user has expressed permission for an implementation to, e.g. access the device's battery level, the implementation MUST seek the user's express permission if and when any additional function is called on this API.

Some User Agents will have prearranged trust relationships that do not require such user interfaces. For example, while a Web browser will present a user interface when a Web site performs a system information request, a widget runtime may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorize access to system information.

Privacy considerations for recipients of system information

Recipients should only request system information when necessary. Recipients should only use the system information for the task for which it was provided to them. Recipients should dispose of system information once that task is completed, unless expressly permitted to retain it by the user. Recipients should also take measures to protect this information against unauthorized access. If system information is stored, users SHOULD be allowed to update and delete this information.

The recipient of system information should not retransmit the system information without the user’s express permission. Care should be taken when retransmitting and use of encryption is encouraged.

Recipients should clearly and conspicuously disclose the fact that they are collecting system data, the purpose for the collection, how long the data is retained, how the data is secured, how the data is shared if it is shared, how users can access, update and delete the data, and any other choices that users have with respect to the data. This disclosure should include an explanation of any exceptions to the guidelines listed above.

Additional implementation considerations

Further to the requirements listed in the previous section, implementors of this API are also advised to consider the following aspects that can negatively affect the privacy of their users: in certain cases, users can inadvertently grant permission to the User Agent to disclose their system information to Web sites. In other cases, the content hosted at a certain URL changes in such a way that the previously granted permissions no longer apply as far as the user is concerned. Or the users might simply change their mind.

Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures are an implementation responsibility and not prescribed by this specification. However, in designing these measures, implementers are advised to enable user awareness of system information sharing, and to provide easy access to interfaces that enable revocation of permissions.

API Description & Properties

System Properties

A property is defined as a set of related device characteristics. For instance, the Power property contains all the characteristics that relate to the device's electrical power supply. Properties are accessible using the functions defined by the SystemInfo interface below. A property is characterized by the following elements:

The name of a property (or its URI, interchangeably) is used in the functions of the SystemInfo interface to identify the property accessed. When a success callback resulting from calling one of those functions is invoked, the API MUST pass an instance of the property's interface.

Some of the properties below are defined as enumerable, meaning that more than one instance of the property's value type exist on the system. For instance, a multi-processor system would report as many instances of Cpu as the number of processors. When requesting the value of an enumerable property, the id attribute of the Options interface is used to differentiate between multiple instances.

The non-normative figure below illustrates the contents and relationship of all the properties defined in the following sections.

graphical representation of the property structure

The SystemInfo interface

This interface contains the functions that enable access to the properties defined in the following sections. Objects implementing the Navigator interface (e.g. the window.navigator object) must also implement the NavigatorSystem interface [[!NAVIGATOR]]. An instance of NavigatorSystem would then be obtained by using binding-specific casting methods on an instance of Navigator.

readonly attribute SystemInfo system
The root node from which the system information functionality can be accessed.
PendingOp get()
This function retrieves the current state of a given system property. When called, the function MUST immediately return and asynchronously acquire the current state of the requested property. If it is successful the success callback MUST be invoked and return an object containing the information provided by the property. If an error occurs, and an errorCallback function was passed to the function invocation, it is called and is passed an Error object indicating the cause of error.
DOMString propertyId
The URI or name of the property to retrieve. The URI of a property is the concatenation of the string
SuccessCB successCallback
function called when the properties have been successfully retrieved
optional ErrorCB? errorCallback
function called when an error occurred while retrieving the properties
optional Options options
An object containing the various options for fetching the properties requested
PendingOp watch()
The watch function allows tracking the change of one or several system properties. When called, it immediately returns and then asynchronously starts a watch process defined as the following set of steps:
  1. Acquire the system's current values for the property requested. If successful invoke the associated successCallback, passing the resulting property value an object of the type indicated by the property's value type in the definitions below. If the attempt fails, and the method was invoked with a non-null errorCallback argument, this method invokes the errorCallback, passing an ErrorCB object which reflects the cause of the error.
  2. Register to receive system events that indicate that the status of the requested properties may have changed
  3. When a system event is successfully received invoke the associated successCallback, passing an object containing the property values. If an error occurs and the method was invoked with a non-null errorCallback argument, this method MUST invoke the errorCallback with an ErrorCB object as an argument.
  4. Repeat the previous step until the cancel method of the PendingOp object returned by this watch function is invoked.
DOMString propertyId
Property URI or name identifying the property to track.
SuccessCB successCallback
function called when the properties have been successfully retrieved
optional ErrorCB? errorCallback
function called when an error occurred while retrieving the properties
optional Options options
An object containing the various options for fetching the properties requested
PendingOp set()
The set function modifies the current value of of a system property. When called, the function immediately returns and asynchronously attempts to set the requested state of the value identified by the propertyId attribute. If it is successful the success callback is invoked and is passed an object containing the requested information. The type of that object is indicated in the property definitions below. If an error occurs, or if the system does not allow the value to be modified, then the errorCallback function is invoked and is passed an Error object indicating the cause of error.

Not all property attributes can be modified. Each property interface definitions indicates, through the readonly keyword whether an attribute is allowed to be modified.

DOMString propertyId
The URI or name of the property to retrieve.
optional Object value
An object containing the values to modify, as well as the id to designate which instance to modify
SuccessCB successCallback
function called when the property have been successfully modified
optional ErrorCB? errorCallback
function called when an error occurred while modifying the property

All functions return a PendingOp object, defined in [[!CORE-DEVICE]], which has a cancel function allowing the asynchronous operation to be interrupted.

Callback interfaces

void onSuccess()
optional Object obj
The return object of a successful asynchronous operation.
void onError()
Error error
The error object of an unsuccessful asynchronous operation.

The Error interface

const unsigned short PERMISSION_DENIED = 0
The application context does not have permission to access this property
const unsigned short INFORMATION_UNAVAILABLE = 1
The property accessed is unavailable on this device (e.g. the battery level on a device that only has an external power source).
const unsigned short INVALID_VALUE = 2
One or more of the values in the Options object passed was invalid. For example, if the highThreshold attribute is set to a value greater than 1.0 for the CpuLoad property.
const unsigned short READ_ONLY = 3
The property that has been passed to the set function that has triggered this callback cannot be modified.
const unsigned short TIMEOUT = 4
The length of time specified by the timeout option has elapsed before the implementation could successfully retrieve the requested property.
readonly attribute unsigned short code
The code attribute SHOULD contain one of the error values defined in this specification. An implementation MAY define additional error codes, but those MUST NOT use the numeric values defined here.

The Options interface

attribute unsigned long timeout
The number of milliseconds beyond which the operation must be interrupted and the cancel method of the PendingOp object must be called.
attribute double highThreshold
This attribute has no effect on the get method. On the watch method, it indicates that the successCallback is only be triggered if the property is a number and its value is greater than or equal this number.
attribute double lowThreshold
This attribute has no effect on the get method. On the watch method, it indicates that the successCallback is only be triggered if the property is a number and its value is lower than or equal this number. If both highThreshold and lowThreshold parameters are specified, the success callback is triggered if and only if the property value is either lower than the value of lowThreshold or higher than the value of hiThreshold.
attribute DOMString id
In order to differentiate between instances, this attribute is used to indicate the request's target instance. The list of available identifiers would normally be retrieved first through querying the relevant property (e.g. the sources attribute of CpuState). If a property requested does not support multiple instances and an id parameter is passed, then it MUST be ignored. If a property does support multiple instances and an id parameter is passed that does not correspond to any existing instance, then the error callback MUST be called with a code set to INVALID_VALUE.

The SystemDevice interface

This interface gathers attributes shared by all properties describing system devices (i.e. all the enumerable properties). Examples: single battery units, CPU, or network connections.

readonly attribute DOMString? info
A free-form string describing this device, e.g. the name of its manufacturer.
readonly attribute DOMString id
A free-form string identifying this device. The value of this element MUST be unique within the list reported in the object enumerating this device, e.g. the Power object.

Power

The properties below expose the device's power information, either internal (battery) or external.

ECMAScript Example

// Alert the user when the power level is below 20%

navigator.system.watch("Power",success,null,{lowThreshold:0.2});

function success(power) {
  alert("Low battery level: "+power.level);
};

The Power Property

This property reflects the general state of the system's power sources

Find the corresponding DCO properties everywhere

readonly attribute float? level
Specifies how much the internal power source remains, scaled from 0 to 1. A value of 0 means that the battery level is lowest before the system enters shutdown mode, and 1 indicates that the system's charge is maximal. Any threshold parameter used in a watch function to monitor this property applies to this attribute.
readonly attribute unsigned long? timeRemaining
Represents the estimated time remaining in seconds before the system enters shutdown mode. If isExternal is true, this value MUST be null, meaning that there is essentially infinite time remaining.
readonly attribute boolean isExternal
If true the device is currently powered by an external source. If false the device is currently powered by an internal source.
readonly attribute boolean isCharging
Indicates whether the internal power source is currently charging. If isExternal is false, this value MUST be false, meaning that the battery is currently powering the system, and is therefore depleting.

CPU

This section defines interfaces that expose the system's CPU information, including type, specifications, current system load information.

ECMAScript Example

//Monitor and display the CPU load

navigator.system.watch("Processing",success);

function success(cpu) {
  var s="CPU load: "+cpu.load;
  document.getElementById("cpuIndicator").innerHTML="CPU load: "+(cpu.load*100)+"%".
}

The CPU Property

This property reflects the state of the CPUs available to this system.

readonly attribute float load
This attribute indicates the current CPU load, as a number between 0.0 and 1.0, representing the minimum and maximum values allowed on this system. Any threshold parameter used in a watch function to monitor this property applies to this attribute.

Thermal

The properties described in this section expose the system's temperature, as reported to the various internal thermometers.

ECMAScript Example

// Check the thermal state and display a warning if it is above a certain level

navigator.system.get("Thermal",success);

function success(thermal) {
  if (thermal.state > 0.9)
    document.getElementById("tempIndicator").style.background-color = "red";
};

The Thermal property

This property provides information on the global temperature state of the system

readonly attribute float state
This attribute indicates the current thermal status, as a number between 0 and 1 representing the minimum and maximum operating values allowed by this system. On devices that have multiple thermometers, this implementation-defined value should reflect the global temperature of the system.

Network

This interface can be used by applications to determine the state of the network interface used by the system.

ECMAScript Example

// Find if the current connection is WiFi, and if so monitor its signal strength
navigator.system.get("Network",success,null);

function success(connection) {
  if (connection.type===connection.TYPE_IEEE802_11)
    navigator.system.watch("WifiConnection",wifiWatchCB);
}

function wifiWatchCB(connection) {
  document.getElementById(indicator, "Wireless "+connection.essid+" at "+(connection.signalStrength*100)+"%");
}

The Network Property

This property provides information on the system's connection to the network

const unsigned short TYPE_UNKNOWN = 0
The API is unable to determine the network technology.
const unsigned short TYPE_ETHERNET = 1
Indicates that the network technology is IEEE802.3, otherwise known as ethernet.
const unsigned short TYPE_IEEE802_11 = 2
Indicates that the network technology is IEEE802.11.
const unsigned short TYPE_GSM = 3
Global System for Mobile communications.
const unsigned short TYPE_GPRS = 4
General Packet Radio Service.
const unsigned short TYPE_EDGE = 5
Enhanced Data Rates for GSM Evolution.
const unsigned short TYPE_CDMA = 6
Code Division Multiple Access.
const unsigned short TYPE_WiMAX = 7
Worldwide Interoperability for Microwave Access.
const unsigned short TYPE_iDEN = 8
Integrated Digital Enhanced Connection.
const unsigned short TYPE_TETRA = 9
Terrestrial Trunked Radio.

The associated Connection object is a CellularConnection object.

const unsigned short TYPE_UMTS = 10
Universal Mobile Telecommunications System. Otherwise known as 3G.

The associated Connection object is a CellularConnection object.

const unsigned short TYPE_BLUETOOTH = 11
BlueTooth
const unsigned short TYPE_IRDA = 12
Infrared
const unsigned short TYPE_USB = 13
USB
readonly attribute unsigned short type
This attribute indicates the network technology in use on a network.
readonly attribute unsigned long currentDownloadBandwidth
The current real-time download bandwidth, in Kbits/s.
readonly attribute unsigned long currentUploadBandwidth
The current real-time upload bandwidth, in Kbits/s.
readonly attribute unsigned long maxDownloadBandwidth
This property represents the maximum download bandwidth offered by this network connection, measured in Kbits/s.
readonly attribute unsigned long maxUploadBandwidth
This property represents the maximum upload bandwidth offered by this network connection, measured in Kbits/s.
readonly attribute float? currentSignalStrength
This connection's signal strength, as a normalized value between 0 (no signal detected) and 1 (the level is at its maximum value). . This value MUST be null if this connection is wired.
readonly attribute DOMString macAddress
The MAC address of this connection. The format of this string MUST be the standard notation for MAC addresses: six groups of two hexadecimal digits, separated by colons (:), e.g. 01:23:45:67:89:ab [[!IEEE802-3]]
readonly attribute DOMString ipAddress
The IP Address assigned to the device by the network bearer. An implementation MUST support both IPv4 and IPv6.
readonly attribute DOMString? ESSID
The Extended Service Set Identifier (ESSID) if the type attribute is TYPE_IEE802.11, null otherwise.
readonly attribute DOMString? apn
The Access Point Name associated to a network bearer, if applicable. null otherwise.
readonly attribute DOMString? operatorName
The name of the cellular connection's operator if applicable, null otherwise
readonly attribute boolean? roaming
Whether the connection is set up while the device is roaming, if applicable. null otherwise

Should we gather all of GSM, GPRS, EDGE, CDMA, TETRA, UMTS under a singe "CELL" type? They could be differentiated by maxBandwidth, if needed.

Sensors

The properties defined below expose the values of external sensors, reflecting the device's environment such as temperature, ambient brightness or ambient sound.

ECMAScript Example

// Automatically adjust the screen brightness if the ambient brightness is above a certain level

navigator.system.watch("AmbientLight",success, {maxThreshold: 0.9});

function success() {
  navigator.system.get("OutputDevices", 
                       function(devices) {
                         for(var i=0; i<devices.displays.length; i++)
                           navigator.system.set("Display",{id: devices.displays[i].id, brightness: 0.9});
                       });
}

Ambient Light

The AmbientLight Property

This property provides information about the global level of ambient light around the device.

readonly attribute float intensity
A normalized value representing the overall ambient light around the device. The way this value is determined should be an implementation-defined combination of the values reported by each ambient light sensor available.

Ambient Noise

The AmbientNoise property

This property provides information about the global level of ambient noise around the device.

readonly attribute float value
The ambient noise intensity around the device, computed by this system's sensors, in decibels (dB)
readonly attribute float min
The minimum ambient noise intensity that this system's sensors are able to report, in decibels (dB)
readonly attribute float max
The maximum ambient noise intensity that this system's sensors are able to report, in decibels (dB)

Ambient Temperature

The AmbientTemperature Property

This property provides information about the temperature around the device.

readonly attribute float value
This current temperature around the device, in degrees Celsius (°C)
readonly attribute float min
The minimum ambient temperature that this system's sensors are able to report, in degrees Celsius (°C)
readonly attribute float max
The maximum ambient temperature that this system's sensors are able to report, in degrees Celsius (°C)

Ambient Atmospheric Pressure

The AmbientAtmosphericPressure Property

This property provides information about the atmospheric pressure around the device.

readonly attribute float pressure
The estimated atmospheric pressure around this device, in kiloPascals (kPa)
readonly attribute float min
The minimum ambient atmospheric pressure that this system's sensors are able to report, in kiloPascals (kPa)
readonly attribute float max
The maximum ambient atmospheric pressure that this system's sensors are able to report, in kiloPascals (kPa)

Proximity

The Proximity Property

This property provides information about the distance of objects around the device.

readonly attribute float distance
The distance from the device to the nearest object, as determined by this device's proximity sensors, in meters (m)
readonly attribute float min
The minimum distance that this system's sensors are able to report, in meters (m)
readonly attribute float max
The maximum distance that this system's sensors are able to report, in meters (m)

Audio and Video Codecs

The properties below expose the device's audio and video codec capabilities.

ECMAScript Example

// Find if this device supports MIDI
navigator.system.get("AVCodecs",success);

function success(codecs) {
  for (var i=0;i<codecs.length;i++)
    if (codecs[i].compFormat === "MP3") {
      // ... use MP3 for encoding ...
      break;
    }
}

The AVCodecs property

This property exposes information about the audio/video codecs available to this system

readonly attribute AudioCodec[] audioCodecs
Audio codecs on this device
readonly attribute VideoCodec[] videoCodecs
Audio codecs on this device

The AudioCodec Property

This property exposes information on a single audio codec available to this system. Is it enumerable.

readonly attribute DOMString compFormat
Free-form information on the compression format. Examples : "G.711", "MP3", "MIDI"
readonly attribute boolean encode
true if this device supports audio encoding, false otherwise.
readonly attribute boolean decode
true if this device supports audio decoding, false otherwise.

The VideoCodec Property

readonly attribute sequence<DOMString> compFormats
Supported compression format names. Example : "AVI", "ogg"
readonly attribute sequence<DOMString> containerFormats
Supported container format names. Example : "AVI", "ogg"
readonly attribute boolean hwAccel
true if the codec includes hardware acceleration support, false otherwise.
readonly attribute sequence<VideoProfile> profiles
The list of profiles available for this codec.
readonly attribute sequence<FrameType> frametypes
The list of frame types supported by the codec
readonly attribute sequence<RateControl> ratetypes
The list of rate control options supported by the codec

The VideoProfile Property

readonly attribute DOMString name
Profile name. Examples : "Simple","Main", "High", "Advanced"

The FrameType Property

readonly attribute DOMString name
Frame type name. Examples : "PROGRESSIVE","INTERLACED"

The RateControl Property

readonly attribute DOMString name
Rate control type name. Examples : "CBR","VBR"

Storage

This set of properties expose a device's storage units and their properties, like type (hard Disk, memory card, etc.) and capacity

ECMAScript Example

// Check each storage and warn if almost full 
            
navigator.system.get("Storage", success);
            
function success(units) {
  for (var i=0;i<units.length;i++)
    if (units[i].capacity / units[i].availableCapacity > 0.95)
      alert("Storage unit '"+units[i].info+"' almost full. You may want to free some space.");
}

The Storage Property

This property exposes the data storage devices connected to this system.

readonly attribute StorageUnit[] units
The array of storage units connected to this device

The StorageUnit Property

This property exposes a single storage device connected to this system. It is enumerable.

const unsigned short TYPE_UNKNOWN=0
type is set to this value when the type of this device is unknown to this API.
const unsigned short TYPE_HARDDISK=1
When type has this value, then this device is a hard disk
const unsigned short TYPE_FLOPPYDISK=2
When type has this value, then this device is a floppy disk
const unsigned short TYPE_OPTICAL=3
When type has this value, then this device uses optical storage technology (CD, DVD, Holographic)
const unsigned short TYPE_RAM=4
When type has this value, then this device uses solid-state RAM technology (chip, memory card)
readonly attribute unsigned short type
The type of pointing device. The value is one of the constants defined for this type.
readonly attribute boolean isReadWrite
true when this device supports software modification, else otherwise.
readonly attribute unsigned long capacity
The amount of data that this device can hold, in bytes. A watch operation operating on an object of type StorageUnit must invoke the success callback only when this attribute has changed
readonly attribute unsigned long availableCapacity
The amount of available data that this device can hold, in bytes
readonly attribute boolean isRemoveable
true if this unit can be removed from the system (e.g. a memory card unplugged, or a disk ejected), false otherwise

Output Devices

This section gathers system properties related to this device's output devices: screens, sound systems, etc.

Do we need information about active devices, e.g. in order to be able to see which screen is currently being in use, or to control which set of speakers should be activated? If so how do we specify it? Through an "active" flag on each device (hard to watch), or through a pointer (e.g. currentDisplay in OutputDevices) which would mean only one device is active at a time, which might not always be correct in cases like several active keyboards

ECMAScript Example

// Set the brightness of all the displays to their maximum value

navigator.system.get("OutputDevices", 
                     function(devices) {
                       for(var i=0; i<devices.displays.length; i++)
                         navigator.system.set("Display",{id: devices.displays[i].id, brightness: 1});
                     });

The OutputDevices Property

This property provides information on the output devices (displays, audio) available on this system

readonly attribute Display[] displays
An array of all the display devices connected to this system
readonly attribute Audio[] audioDevices
An array of all the output audio devices connected to this system

The Display property

This property exposes information on a single display device available to the system. Is it enumerable.

The Display interface defined below inherits from the Screen interface as defined in [[!CSSOM-VIEW]]

const unsigned short ORIENTATION_UNKNOWN = 0
The device is not able to determine its orientation.
const unsigned short ORIENTATION_LANDSCAPE = 1
The display orientation is landscape.
const unsigned short ORIENTATION_PORTRAIT = 2
The display orientation is portrait.
const unsigned short ORIENTATION_INVERTED_LANDSCAPE = 3
The display orientation is inverted landscape.
const unsigned short ORIENTATION_INVERTED_PORTRAIT = 4
The display orientation is inverted portrait.
attribute unsigned short orientation
The display orientation from the constants listed in this object.
attribute float brightness
The current brightness, from 0 to 1
attribute float contrast
The current contrast, from 0 to 1
attribute boolean blanked
true if this display is currently blanked, false otherwise
readonly attribute unsigned long dotsPerInchW
Resolution of this device, along its width, in dots per inch.
readonly attribute unsigned long dotsPerInchH
Resolution of this device, along its height, in dots per inch.
readonly attribute float physicalWidth
The display's physical width in centimeters
readonly attribute float physicalHeight
The display's physical height in centimeters

Are we being short-sighted in only listing four orientations? Would it make sense to have it be an angle, except that in most cases it would only change in 90° increments?

The AudioDevice Property

This property exposes information on a single audio output device available to this system. It is enumerable.

const unsigned short TYPE_UNKNOWN=0
type is set to this value when the type of this device is unknown
const unsigned short TYPE_SPEAKER=1
type is set to this value when this device is a loud speaker
const unsigned short TYPE_HEADPHONES=2
type is set to this value when this device is a set of headphones
readonly attribute unsigned short type
The type of audio output device. The value is one of the constants defined for this type.
readonly attribute unsigned long freqRangeLow
Frequency range, low value, in Hz
readonly attribute unsigned long freqRangeHigh
Frequency range, high value, in Hz

Input Devices

The properties defines below expose the input devices connected to the system (e.g. mouse, keyboard, camera).

Should we have a notion of active or selected device, e.g. which camera is currently used, or which display is the one currently drawn on. We could use current* like with Power, but that restricts to one active device at a time. Alternatively, there could be an active flag in each device. But that would make watch() messy, since we would have to extend the definition of watched events to sub-sub-field modifications

ECMAScript Example

// Check if the device supports multitouch

navigator.system.get("InputDevices", 
                     function(devices) {
                       for(var i=0; i<devices.pointingDevices.length; i++)
                         if (devices.pointingDevices[i].supportsMultiTouch) {
                           applicationParams.hazMultiTouch = true;
                           break;
                         }
                     });

The InputDevices Property

readonly attribute PointingDevice[] pointingDevices
The list of physical pointing devices attached (e.g. mouse, tablet, touchscreens)
readonly attribute Keyboard[] keyboards
The list of keyboards attached
readonly attribute Camera[] cameras
The list of cameras attached
readonly attribute Microphone[] microphones
The list of microphones attached

The PointingDevice Property

This property exposes the pointing devices (mouse, touch screen, gesture sensor). It is enumerable.

const unsigned short TYPE_UNKNOWN=0
When the type attribute has this value, then the type of this pointing device is unknown.
const unsigned short TYPE_MOUSE=1
When the type attribute has this value, then this device is a mouse
const unsigned short TYPE_TOUCHSCREEN=2
When the type attribute has this value, then this device is a touch screen
const unsigned short TYPE_LIGHTPEN=3
When the type attribute has this value, then this device is a light pen
const unsigned short TYPE_GESTURE=4
When the type attribute has this value, then this device is a gesture device
const unsigned short TYPE_TABLET=5
When the type attribute has this value, then this device is a graphics tablet
readonly attribute unsigned short type
The type of pointing device. The value is one of the constants defined for this type.
readonly attribute boolean supportsMultiTouch
true when this device supports the multi-touch method of interaction, else otherwise.

The Keyboard Property

This property exposes the keyboards and keypads connected to this system. It is enumerable.

const unsigned short TYPE_UNKNOWN=0
When the type attribute has this value, then this device is of a type unknown to this API.
const unsigned short TYPE_KEYBOARD=1
When the type attribute has this value, then this device is a full keyboard
const unsigned short TYPE_KEYPAD=2
When the type attribute has this value, then this device is a keypad
readonly attribute unsigned short type
The type of pointing device. The value is one of the constants defined for this type.
readonly attribute boolean isHardware
true when this device is a physical keyboard, else if it is a software keyboard.

The Camera Property

This property exposes the cameras connected to this system. It is enumerable.

readonly attribute boolean supportsVideo
true when this device supports recording video, else otherwise.
readonly attribute boolean hasFlash
true when this device supports has a flash, else otherwise.
readonly attribute unsigned long sensorPixels
The number of image sensor elements (pixels) of this camera
readonly attribute float? maxZoomFactor
The maximum zoom factor of this camera. This value MUST be null if the camera does not have a zoom (whether physical or digital)

Use focal length instead? And shutter speed/aperture/ISO/sensor type?

The Microphone Property

This property exposes the microphones connected to this system. It is enumerable.

const unsigned short TYPE_UNKNOWN=0
type is set to this value when the type of this device is unknown to this API.
const unsigned short TYPE_MICROPHONE=1
type is set to this value when this device is a microphone
const unsigned short TYPE_LINEIN=2
type is set to this value when this device is a line-in connector
readonly attribute unsigned short type
The type of audio input device. The value is one of the constants defined for this type.
readonly attribute unsigned long freqRangeLow
Frequency range, low value, in Hz
readonly attribute unsigned long freqRangeHigh
Frequency range, high value, in Hz

Extensibility

This specification allows vendor-specific properties to be made available to the SystemInfo interface. The URI of those properties MUST NOT start with the string http://www.w3.org/2009/dap/SysInfo/.

Implementers should be aware of other standard device APIs when planning extensions, in order to avoid overlapping with existing work, in particular that of the W3C Device API and Policy Working Group.

extensibility of enumerated constants, e.g. connection types

Requirements & Use cases

make a separate document?

Requirements

Power

  • A conforming implementation MUST provide a method to retrieve one-shot power source information.
  • A conforming implementation MUST provide a method to retrieve one-shot power remaining information.
  • A conforming implementation SHOULD provide a power source change events.
  • A conforming implementation SHOULD provide a power level change events.
  • A conforming implementation SHOULD provide power level change events based on thresholds.

CPU

  • A conforming implementation MUST provide a method to retrieve information about the number of concurrent threads that can run on the CPU.
  • A conforming implementation MUST provide a method to retrieve information about the CPU utilization.
  • A conforming implementation SHOULD provide a method to retrieve information about the current CPU frequency.
  • A conforming implementation SHOULD provide a method to retrieve information about the maximum CPU frequency.
  • A conforming implementation SHOULD provide a method to retrieve information about the CPU brand.
  • A conforming implementation MAY provide a methods to retrieve additional information about the CPU.

Display

  • A conforming implementation SHOULD provide information about the dots-per-inch (DPI) of the display.
  • A conforming implementation SHOULD provide a method to retrieve one-shot screen blank information.
  • A conforming implementation SHOULD provide screen blank events.
  • A conforming implementation MUST provide one-shot display orientation information.
  • A conforming implementation MUST provide display orientation change events.
  • A conforming implementation MUST provide one-shot display brightness information.
  • A conforming implementation MUST provide display brightness change events.
  • A conforming implementation MAY provide information and events about external displays.
  • A conforming implementation MAY provide events about display color depth.
  • A conforming implementation MAY provide information and events about display device refresh rate.

Connection

  • A conforming implementation MUST provide a method to detect the technology that a network bearer uses (e.g. 802.11a, CDMA, WiMAX, etc.)
  • A conforming implementation MUST provide a method to detect the quality of the connection to the network bearer.
  • A conforming implementation MUST provide a method to detect whether a specified service is available. This method SHOULD be asynchronous.
  • A conforming implementation MUST provide a events about the availability of a specified service.
  • A conforming implementation MUST provide a method to detect the quality of the connection to a specified service.
  • A conforming implementation MUST provide a method to detect whether the device currently has a valid network connection. This method SHOULD be synchronous.
  • A conforming implementation MUST provide a method to detect changes in the devices network status (e.g. radio turned on or signal no longer available).
  • A conforming implementation MUST provide information about the current network bearer.
  • A conforming implementation MAY provide information about the default network bearer.
  • A conforming implementation MAY provide information about the preferred network bearer.
  • A conforming implementation MAY provide a method to change the current network bearer.
  • A conforming implementation SHOULD provide a method to detect whether a device that is using a cellular network is currently roaming.
  • A conforming implementation MAY provide a method to detect geolocation based on cell tower triangulation calculations.
  • A conforming implementation SHOULD provide a method to detect the ID of the current network bearer.
  • A conforming implementation SHOULD provide a method to detect the type of encryption in use by a network bearer.
  • A conforming implementation SHOULD provide a method to detect the operator, MMC, and MNC of a PLM Network.
  • A conforming implementation SHOULD provide IP Address Table change events.
  • A conforming implementation SHOULD provide Route Table change events.
  • A conforming implementation MUST provide connected events.
  • A conforming implementation MUST provide disconnected events.

Thermal

  • A conforming implementation SHOULD provide the ability to list temperature from multiple thermometers.
  • A conforming implementation SHOULD provide a method to detect the thermal target of a thermometer.
  • A conforming implementation MAY provide a method to detect the ID of the thermometer.
  • A conforming implementation MUST provide a method to detect temperature.
  • A conforming implementation SHOULD provide a method to monitor temperature changes based on thresholds.

Audio

  • A conforming implementation MUST provide a list of audio codecs available on the device
  • A conforming implementation MUST provide a list of audio output devices (speakers etc.)
  • A conforming implementation MUST provide a list of audio input devices (microphones, software)
  • A conforming implementation SHOULD provide audio architecture information.

Video

  • A conforming implementation MUST provide a list of codecs available on the device.
  • A conforming implementation SHOULD provide video architecture information.

Ambient Light Sensor

Storage

Input

  • A conforming implementation MUST provide information about the presence of a touch screen.
  • A conforming implementation MUST provide information about the existence of mouse hover events.
  • A conforming implementation SHOULD provide information about the presence of a screen that supports multi-touch.
  • A conforming implementation SHOULD provide information about presence of a physical keyboard.
  • A conforming implementation SHOULD provide information about the size of the keyboard (e.g. whether it is a thumb keyboard).
  • A conforming implementation MAY allow an application to detect whether an on-screen keyboard is visible.
  • A conforming implementation MAY allow an application to monitor when an on-screen keyboard appears and disappears.
  • A conforming implementation MAY provide a method for applications to monitor the attachment and detachment of physical pointing devices.
  • A conforming implementation MAY provide a method for applications to monitor the attachment and detachment of physical keyboard devices.

Use Cases

Add examples

Power

User Watches Video Content on Device on battery power
The user has opened a video playback application and the application attempts to provide the optimal viewing experience for the device. During the video playback, the battery level has reached a low level that will prevent the playback to finish. The application displays a non-intrusive notification that the device needs to be plugged in to ensure the video playback to finish.

CPU

User Watches Video Content on Device
The user has opened a video playback application and the application attempts to provide the optimal viewing experience for the device. The content provider has a multithreaded decoder so the application use the Cpu API to see if the CPU would be able to take advantage of concurrent threads. It then checks to see if the CPU is currently busy by looking at current usage and comparing current frequency to maximum frequency. If the application determines that playback can proceed without hardware acceleration on the system in its current state, playback proceeds. Otherwise, the application either looks for hardware acceleration capabilities, recommends that the user shut down other applications that are using device CPU resources, or streams lesser content that can be decoded with fewer CPU resources.
Service Provider pushes software on to user device
A service provider wants to push a software package out to the customer's device. However, they want the installation to be unobtrusive. They use the CPU API to register to be notified when the CPU usage falls below 10% for 5 consecutive samples taken one second apart.
user installs additional software from a repository
The user wants to install additional software on to her device from a repository. before downloading the software, the repository installation application checks to ensure that system requirements are met, and it uses the cpu api to check if the host device cpu is a supported architecture. if the cpu architecture is not supported, the installation is cancelled before the software is downloaded, thus minimizing the network resources required.
user installs additional software from a repository--case 2
The user wants to install additional software on to her device from a repository. the application provider supports multiple platforms but each installation package only supports one platform in order to minimize network resource utilization. before downloading the plugin, the repository installation application uses the cpu api to determine which installation package to download. with the smaller installation packages, the user's experience is optimized, especially over slower network connections.

Display

Application detects that screen is blank
A web application has a lot of sprites, UI elements, and frequent server queries that consume a lot of power. The user stops actively interacting with the device and the screen blanks or the screen saver begins. The application detects this change and stops all non-essential actions that consume power.
The user changes the orientation of the device
While reading content provided by a web application in landscape orientation, the user rotates the device to a portrait orientation because the content is taller than it is wide. The application detects the change and reflows the content to better fit in portrait orientation.
The web application is displayed on screens that vary greatly in physical size
Recognizing market opportunity, a developer targets her application for small hand-held devices as well as television screens and very large electronic advertising canvases. The developer uses DPI information in order to determine the ideal size of UI widgets in order to provide the most ideal viewing experience across screens.

Connection

The use cases for this module are critical to forming a realistic picture of what kinds of information are going to be valuable for the web application that wants delivery context network information. The primary use case is: application wants to know about the network connection so that it can adjust its behavior.

User accesses web content based on type and quality of network connection.
A video viewing web application can makes use of the API to detect the connection speed and present the user with appropriate encodings of the video that will provide a viewing experience that is less likely to be interrupted. Alternatively, the application may monitor signal strength and assist the user with re-orienting the device or changing locations so that the viewing experience can be of higher quality.
Web applications use connection context to provide users seamless access to localized services.
As a user drives along in their car, a web application running on a dashboard console periodically chooses the most appropriate network connection to use. As the user pulls into a coffee shop parking lot the application changes from 3G cellular to the coffee shop's 802.11 network. This allows the app to reduce the user's connection fees and take advantage of a better connection speed. The application may present the user with several options if it cannot choose itself.

Thermal

Application can throttle activity based on device temperature.
A web application can take device temperature into account in order to throttle activity and avoid degraded performance or crashes due to heat from intense hardware use. For example, some devices include RFID radios with >1 watt power amplifiers and can generate a lot of heat. Throttling performance may avoid degradation or crashes on these devices. In addition the application may present the user with a notification about device temperature and suggest an action or send a notification to an IT web service that indicates the device is "running hot".
A weather monitoring application uses temperature data from automobile temperature sensors.
A web application that runs on a dashboard console could send the temperature outside the car, with additional location information to a weather related web service.

Audio

Application sound themes
A game may detect a devices audio capabilities in order to select a sound theme that takes advantage of 6 audio channels and a subwoofer. Alternatively it may select a sound theme optimized for stereo headphones.
Recording
A outdoors recording application may take advantage of multiple microphones attached to a device in order to record audio from several sources and special orientations at simultaneously.

Video

Encoding video on the device : app requirements and user experience
An application may include features that encode video. Determining the video encode capabilities of the local device allows the application to determine if the device's capabilities meet the needs of the application and the desired user experience.
Encoding video on the device : local vs cloud
An application may intelligently split up the work of encoding video between the local device, based on its capabilities, and a web service in the cloud that encodes video. This may provide for more efficient compute and network resource utilization.

Input

Application adapts to touch screen device with no external pointer
A user who frequently visits a popular music social media site navigates to the site on her new mobile phone. One devices with physical pointing devices and larger screens, the web application presents a complex UI with a lot of functionality. However, when the application detects that the host browser has a smaller touch screen and no external pointing device, it adapts by reducing the complexity of the UI and enlarging widgets to accommodate for finger navigation.
Application adapts to device with no external keyboard
A user who frequently blogs using his laptop finds himself with a great idea but without his laptop. He navigates to the blogging site resigned to type the entry using his thumbs. However the application detects that the delivery context does not have an external keyboard and adapts by enabling predictive text to reduce the number of keystrokes that the user needs to enter.
Application detects the presence of mouse hover events
A user who regularly visits an online video editing and sharing website on his phone decides to try a larger project on his laptop computer with an HD home video. He expects to see the same simplified UI, but is pleasantly surprised to find a UI that is more appropriate for the laptop paradigm. However, because the UI is more complex, there is a lot of functionality that he does not know how to use. Fortunately, the application detect that the user is on a system with mouse in/out/hover events, and so it uses those events to familiarize the user with the new functionality.

Acknowledgements

The DAP Working Group would like to acknowledge the people outside of the DAP Working Group who helped with the process of developing this specification. Specifically, many thanks to Clayne Robison and Andy Idsinga at Intel Corporation for their contributions.