Contents

1 Introduction

The Device Status API provides the means to get information about different "aspects" of a device. For example, you can query the battery to get its level of charge or you can query the operating system to see who the vendor is.

This API uses a kind of tree model to allow developers to get at the various bits of data about things on a device. The tree model is illustrated in figure 1: at the root you find aspects, which contain components, which contain properties - each of which is formally defined below.

Aspect

An aspect is an abstract namable thing (e.g., a "Device", "Battery", "Display", etc.) that the user agent knows about and can interact with. An aspect can contain one or more components.

Component

A component is a concrete instance of an aspect (e.g., a real battery in the device, the real screens of the device). As devices can contain more than one instance of the thing being referred to by an aspect (e.g. two screens, three batteries, two SIM cards), each real instance of an aspect is referred to as a component. Each component has its own unique component name, which is assigned by the user agent and serves as the component's identifier for the life of the application (e.g., "screen_1", "battery2", "os", "hdd", "SDCard").

This specification reserves two special components names ("_active" and "_default") which a user agent MUST NOT use when generating.

Property

A property of an component is something that can be queried to returns data (e.g., how much charge a battery has, if the WiFi is connected or not, the SSID of a WiFi network).

A user agent supports aspect X if the user agent can verify that the aspect (hardware or software) exists on the device and/or has not been disabled (either by policy or by a feature declaration).

A user agent supports aspect X and property Y if the user agent supports the aspect and is able to query property Y to retrieve its data.

1.1 Default and active components

To make the Device Status API easier to work with, this specification reserves two special component names ("_default" and "_active"). These two component names can be used by a developer in the API as proxies for either a default component or active component.

Default component:

The component that is the default component for a given aspect, which may or may not be the active component.

In ECMAScript, a developer uses the string "_default" to refer to the default component.

Active component:

The component that is the acitve component for a given aspect, which may or may not be the default component.

In ECMAScript, a developer uses the string "_active" to refer to the active component.

2 Features strings

A device status feature declaration in a widget's configuration document represents a developer's intention to access some, or all, of the aspects defined in this specification as well as use the Web IDL interfaces specified in the Device Status API.

This specification defines three device status feature strings that can be used by a developer. At least one needs to be present in a widget's configuration document in order for the API to be made available at runtime. However, which device status feature string is declared determines which aspects are made available by the user agent at runtime: the aspects corresponding to a feature string that a user agent makes available at at runtime are referred to as the enabled aspects.

The device status feature strings are as follows:

http://wacapps.net/api/devicestatus.deviceinfo

Only the following device-information aspects are available to the application (all others are disabled):

• Battery
• Device
• Display
• MemoryUnit
• OperatingSystem
• WebRuntime

http://wacapps.net/api/devicestatus.networkinfo

Only the following network-information aspects are available to the application (all others are disabled):

• CellularHardware
• CellularNetwork
• WiFiHardware
• WiFiNetwork

http://wacapps.net/api/devicestatus

All aspects (the union of the network information aspects and device-information aspects) are enabled and available to the application.

2.1 Processing feature declaration

A user agent processes feature elements in accordance with the W3C's Widget Packaging and XML Configuration specification.

If the feature-list contains any features whose feature-name exactly matches a device status feature declarations , then the user agent MUST apply the steps for processing a feature declaration.

The steps for processing a device status feature declaration is given by the following algorithm. Only the first feature declaration is respected by the user agent:

1. Let declaration be the first device status feature declaration that was present in the configuration document, ignoring all others.
2. Implement the DeviceapisDeviceStatusManager interface when the widget's start file is instantiated:
   1. For each supported aspect, identify the components and assign each of them a component name, and, where there are more than one component, identify which is the default and track which components are active. It is recommended that the component name assigned by the user agent to a component be something that is "developer-friendly": i.e., that logically relates to the aspect the component represents (e.g., candidats include "screen_1", "battery2", "os", "hdd", "SD-Card").
3. If required, disable any aspects as needed by the particular feature declaration (see each device status feature strings).
4. ignore all other subsequent device status feature declarations.

XML Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <feature name="http://wacapps.net/api/devicestatus"/>
</widget>

The above example shows how a developer declares their intention to access all aspects of the Device Status API.

XML Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <feature name="http://wacapps.net/api/devicestatus.deviceinfo"/>
</widget>

The above example shows a developers intention to access the device information aspects of the Device Status API.

XML Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <feature name="http://wacapps.net/api/devicestatus.networkinfo"/>
</widget>

The above example shows a developers intention to access network information aspects the aspects of the Device Status API.

XML Example

<widget xmlns="http://www.w3.org/ns/widgets">
  <feature name="http://wacapps.net/api/device.networkinfo"/>
  <!-- The rest are ignored -->
  <feature name="http://wacapps.net/api/devicestatus"/>
  <feature name="http://wacapps.net/api/devicestatus.deviceinfo"/>
</widget> 

In the above example, only the network information aspects would be made available.

3 DeviceapisDeviceStatusManager interface

[NoInterfaceObject]
interface DeviceapisDeviceStatusManager {
    readonly attribute  DeviceStatusManager devicestatus;
};
Deviceapis implements DeviceapisDeviceStatusManager;

When an device status feature declaration appears in the widget's configuration document, the user agent implements the DeviceapisDeviceStatusManager interface

3.1 The devicestatus attribute

The devicestatus attribute provides access to Device Status API.

Example

var info = deviceapis.devicestatus;
info.getPropertyValue(
function(model) {
	console.log("Device model is: " + model);
},
null, {
	aspect: "Device",
	property: "model"
});

4 DeviceStatusManager interface

[NoInterfaceObject]
interface DeviceStatusManager {
    DOMString[]? getComponents(DOMString? aspect);

    boolean isSupported(
               DOMString aspect,
               optional DOMString? property);

    PendingOperation getPropertyValue(Function  successCallback,
                                      ErrorCB? errorCallback,
                                      PropQuery query);

    long watchPropertyChange(Function successCallback,
                             ErrorCB? errorCallback,
                             PropQuery query,
                             optional WatchOptions? options);

    void clearPropertyChange(long watchid);
  };

This offers methods to get information about the device status and subscribe to receive notifications of device status changes. To allow for asynchornous notification of changes to the various properties of components, the user agent keeps a list of active watch operations. Each entry in this list is identified by a number, which is unique within its list for the lifetime of the application.

4.1 Example

deviceapis.devicestatus.getPropertyValue(
function(value) {
	console.log("The battery level is at " + value + "%");
},
null, {
	property: "batteryLevel",
	aspect: "Battery"
});

4.2 The getComponents() method

The getComponents() method provides means to get the components of an aspect.

When the getComponents() method is invoked, the user agent MUST run the steps to retrieve the components.

steps to retrieve the components

The steps to retrieve the components are given by the following algorithm. The algorithm returns an array of component names, which may be empty.

1. Run the general invocation checks algorithm. If no exceptions were generated, continue.
2. Let components be an empty array.
3. If the first argument (aspect) null, return components and terminate this algorithm.
4. Let trimmed aspect be the result of trimming any space characters from the front and back of aspect.
5. If trimmed aspect is an empty string or does not exactly match the name of a supported aspect, return null and terminate this algorithm.
6. If trimmed aspect exactly matches the name of a supported aspect:
   2. For each component of the matching aspect, create a DOMString representation of the component name and add it to the components array.
7. Return components.

Example

//displays contain, for example, ["screen1"] 
var displays = deviceapis.devicestatus.getComponents('Display');
console.log("Your device has " + displays.length + " displays");

//iterate through and show the name of each component
for (var i = 0; i < displays.length; i++) {
	var display = displays[i];
	console.log("Display component " + i + ": " + displays[i]);
}

4.3 The isSupported() method

The isSupported() method checks if an aspect is supported and, optionally, if a property that would correspond to a component of that aspect is supported (e.g., a Battery aspect's batteryLevel property).

When invoked, the user agent MUST run the steps to check if an aspect is supported.

Steps to check if an aspect is supported

The steps to check if an aspect is supported are given by the following algorithm. The algorithm returns either true or false.

1. Run the general invocation checks algorithm. If no exceptions were generated, continue.
2. Let trimmed aspect be the result of trimming all white space from the front and back of the first argument.
3. If the user agent does not supports aspect trimmed aspect, return false and terminate this algorithm.
4. If the second argument (property) was passed, and it's not null,
   1. Let trimmed property be the result of of trimming all white space from the front and back of the second argument.
   2. If trimmed property is a supported property of trimmed aspect, then return true and terminate this algorithm.
5. Return false.

Example

if (deviceapis.devicestatus.isSupported('Battery', 'batteryLevel')) {
	console.log("batteryLevel property is available");
} else {
	console.log("batteryLevel property is not available");
}

4.4 The getPropertyValue() method

The getPropertyValue() method asyncrhonously attemps to read the value of a given component. However, if no component is given, the user agent will befault to the active component or the default component of a given aspect.

The steps to get a property value are given by the following algorithm:

1. Run the general invocation checks algorithm. If no exceptions were generated, continue.
2. If either the aspect member or the property member is not present in the third argument (query):
   1. If the second argument (errorCallback) is not an ECMAScript funtion, then terminate this algorithm skipping all steps below.
   2. Let exception be a new DOMException of type "TypeMismatchError", with message "Required aspect or property was not passed." (or similar).
   3. Queue a task to invoke the errorCallback with exception as the argument.
   4. Terminate this algorithm, skipping all steps below.
3. Let aspect name be the result of trimming the value of the aspect member from the third argument (query).
4. If aspect name does not match an enabled aspect:
   1. If the second argument (errorCallback) is not an ECMAScript function, then terminate this algorithm skipping all steps below.
   2. If aspect name is one found in all aspects, but was disabled by policy or via a feature string, then:
      1. Let exception be a new DOMException of type "SecurityError", with message "Access to this component was blocked by policy." (or similar).
   3. If aspect name is not one found in the list of all aspects, then:
      1. Let exception be a new DOMException of type "NotFoundError", with message "Aspect could not be found." (or similar).
   4. Queue a task to invoke the errorCallback with exception as the argument.
   5. Terminate this algorithm, skipping all steps below.
5. Let prop name be the result of trimming the value of the property member from the third argument (query).
6. If the component member is present in query, let component name be the result of trimming component member.
7. If the component name is not component of the aspect aspect name (e.g., {aspect:"Battery", component: "screen1"}:
   1. If the second argument (errorCallback) is not an ECMAScript function, then terminate this algorithm skipping all steps below.
   2. Let exception be a new DOMException of type "InvalidAccessError", with message "Component is not an instance of aspect." (or similar).
   3. Queue a task to invoke the errorCallback with exception as the argument.
   4. Terminate this algorithm, skipping all steps below.
8. If the component member is not present in query:
   1. If the aspect aspect name has an active component, then let component name be "_active". Otherwise, let component name be "_default".
9. If the component component name does not have the property property name (e.g., {aspect:"Battery", component: "_active", "fooBar"):
   1. If the second argument (errorCallback) is not an ECMAScript function, then terminate this algorithm skipping all steps below.
   2. Let exception be a new DOMException of type "NotFoundError", with message "Property not found in component." (or similar).
   3. Queue a task to invoke the errorCallback with exception as the argument.
   4. Terminate this algorithm, skipping all steps below.
10. Let task be a task that does the following:
    1. Let value be the value of property property name of the component component name.
    2. Invoke the successCallback with value as the argument.
11. Let op be and object that implements the PendingOperation interface.
12. Associate task with op, so that if op's cancel() method is invoked, it attempts to remove task for the callbacks task queue.
13. Queue a task task.
14. Return op.

Example

//The "_default" component is implied.
var options = {
	aspect: "Battery",
	property: "batteryLevel"
};

deviceapis.devicestatus.getPropertyValue(
function batteryQuery(value) {
	console.log("Battery is at " + value + "%");
},
null, options);

4.5 The watchPropertyChange() method

The watchPropertyChange() method allows the developer to watch for changes to the properties of components.

When the watchPropertyChange() method is invoked, the user agent MUST run the steps for watching property changes.

Steps for watching the acceleration

The steps for watching property changes is given by the following algorithm:

1. Run the general invocation checks algorithm. If no exceptions were generated, continue.
2. Let subscription id be a user-agent-defined (random or sequential) unique integer that will represent the looping action to be created by invoking this method.
3. Add subscription id to the list of active watch operations.
4. Return subscription id, and then continue running this algorithm asynchronously.
5. Let interval be the value 0.
6. If the fourth argument (options) is present:
   1. If the minChangePercent member is present, and it is a number greater than 0, then let percent interval be the value of minChangePercent.
   2. If the minNotificationInterval member is present, and it is a number, then let interval be the value of minNotificationInterval.
   3. If the maxNotificationInterval member is present, and it is a number, then let max interval be the value of minNotificationInterval.
7. If interval is less than a user-agent-defined value for a the smallest ammount of time between intevals (i.e., to protect the component from being flooded with requests or because it would drain too much battery, etc.), set interval to that user-agent-defined value.
8. If max interval is less than interval, discard max interval.
9. Let old value be the value 0.
10. Wait, at a minimum (optionally more time if needed), the amount of time indicated by the interval. If the max interval was not discarded, and the time waited exceeds the max interval, do this step again (i.e., wait).
11. If the entry for subscription id has been cleared from the list of active watch operations, terminate this algorithm. If subscription id has not been cleared from the list of active watch operations, create a task to run the getPropertyValue() method using successCallback as the first argument, and, if present, errorCallback as the second argument, and query dictionary as the third argument. Discard the resulting PendingOperation object.
12. TODO: Factor in the minChangePercent change value. Only queue the task when the change between the old value and new value is minChangePercent or greater.
13. Queue the task task.
14. Return to step labelled wait.

Example

function propertyChange(value, ref) {
	console.log("New value for " + ref.property + " is " + value);
}

deviceapis.devicestatus.watchPropertyChange(propertyChange, null, {
	property: "batteryLevel",
	aspect: "Battery"
});

4.6 The clearPropertyChange() method

Unsubscribe from notifications for property changes set up by watchPropertyChange.

If a valid watchid argument is passed that corresponds to a subscription already in place, then the watch process MUST immediately terminate and no further callbacks MUST be invoked. If the watchid argument does not correspond to a valid subscription, the method should return without any further action.

Example

function propertyChange(value, ref) {
	console.log("New value for " + ref.property + " is " + value);

	if (id) {
		deviceapis.devicestatus.clearPropertyChange(id);
		console.log(id + " cleared");
	}
}

var id = deviceapis.devicestatus.watchPropertyChange(
propertyChange, null, {
	property: "batteryLevel",
	aspect: "Battery"
});

5 PropQuery dictionary

dictionary PropQuery {
     DOMString component;
     DOMString aspect;
     DOMString property;
};  

The PropQuery provides a way to query an component about a property.

5.1 The component member

The component member represents the component that is to be queried. If it is not present, the user agent will try to use either the active component or the default component for a given aspect (e.g., "screen1").

5.2 The aspect member

The aspect member takes the identifier of an aspect (e.g., "Battery").

5.3 The property member

The property member takes the name of a property of a component ("batteryBeingCharged").

6 Battery aspect

The Battery aspect represents a battery in the device. Components of this aspect have the following properties:

• batteryBeingCharged
• batteryLevel

6.1 The batteryBeingCharged property

The batteryBeingCharged property is a boolean that indicates whether the battery is currently being charged or not. Returns true if the battery is being charged.

6.2 The batteryLevel property

The batteryLevel property is an octet that represents the remaining percentage (0-100) of the battery capacity that available. When the battery is full, the value is 100. When the battery is drained, the value is 0.

7 CellularHardware aspect

The CellularHardware aspect represents the device's hardware that accesses to telephone network. Components of this aspect have the following properties:

• status

7.1 The status property

The status property is a DOMString represented as a SwitchType that indicates the status of the Cellular Hardware.

8 CellularNetwork aspect

The CellularNetwork aspect represents the cellular network being used by the device. Components of this aspect have the following properties:

• isInRoaming
• mcc
• mnc
• signalStrength
• operatorName

8.1 The isInRoaming property

The isInRoaming property is a boolean that indicates if the cellular connection is roaming. A value of true indicates that the connection is roaming.

8.2 The mcc property

The mcc property is a DOMString that represents the country of a mobile network.

8.3 The mnc property

The mnc property is a DOMString that represents the Mobile Network Code (MNC).

8.4 The signalStrength property

The signalStrength property is an octet that represent the signal strength of the cellular network represented as a percentage.

8.5 The operatorName property

The operatorName property is a DOMString that represents the name of the operator of the cellular network.

9 Device aspect

The Device aspect represents the device on which the runtime is running. Components of this aspect have the following properties:

• imei
• model
• vendor
• version

9.1 The imei property

The imei property is a DOMString that represents the International Mobile Equipment Identity (IMEI).

9.2 The model property

The model property is a DOMString that represents the name of the device model, as assigned by the vendor.

9.3 The vendor property

The vendor property is a DOMString that represents the vendor of the device.

9.4 The version property

The version property is a DOMString that represents the device version assigned by the vendor.

10 Display aspect

The Display aspect represents a screen on the device. Components of this aspect have the following properties:

• resolutionHeight
• pixelAspectRatio
• dpiY
• resolutionWidth
• dpiX
• colorDepth

10.1 The resolutionHeight property

The resolutionHeight property is an unsigned short representing the total number of pixels for the height of the screen.

10.2 The pixelAspectRatio property

The pixelAspectRatio property is a float that represents pixel aspect ratio, for example 1.333333333 for a 4:3 aspect. It's always the value of the resolutionHeight devided by the resolutionWidth.

10.3 The dpiY property

The dpiY property is an unsigned short that represents the dots per inch of the display in the Y axis.

10.4 The resolutionWidth property

The resolutionWidth property is an unsigned short representing the total number of pixels for the width of the screen.

10.5 The dpiX property

The dpiX property is an unsigned short that represents the dots per inch of the display in the X axis.

10.6 The colorDepth property

The colorDepth property is an octet that represents the number of bits used for color definition (e.g. 24).

11 MemoryUnit aspect

The MemoryUnit aspect represents a memory component used in the device. This may include RAM, and other storage media. Components of this aspect have the following properties:

• size
• removable
• availableSize

11.1 The size property

The size property is an unsigned long that represents size of a memory component in bytes.

11.2 The removable property

The removable property is a boolean indicating if the memory component can be removed from the device. The value is true if it is possible.

11.3 The availableSize property

The availableSize property is an unsigned long representing the available size of the memory component in bytes.

12 OperatingSystem aspect

The OperatingSystem aspect represents operating system running on the device. Components of this aspect have the following properties:

• language
• version
• name
• vendor

12.1 The language property

The language property is a DOMString representation the locale of the operating system, in the RFC 4646 language tag format.

12.2 The version property

The version property is a DOMString that represents the version of the operating system.

12.3 The name property

The name property is a DOMString representing the name of the operating system.

12.4 The vendor property

The vendor property is a DOMString representing name of the vendor of the operating system.

13 WebRuntime aspect

The WebRuntime aspect represents the user agent. Components of this aspect have the following properties:

• version
• name
• vendor

13.1 The version property

The version property is a DOMString representing the version of the runtime assigned by the vendor.

13.2 The name property

The name property is an DOMString representing the name assigned by the vendor to the runtime.

13.3 The vendor property

The vendor property is an DOMString representing the name of the vendor who sells or created the runtime.

14 WiFiHardware aspect

The WiFiHardware aspect represents hardware in a device that accesses WiFi networks. Components of this aspect have the following properties:

• status

14.1 The status property

The status property is a DOMString represented as a SwitchType that indicates if the WiFi Harware is switched on or off.

15 WiFiNetwork aspect

The WiFiNetwork aspect represents the WiFi Network that the device is connected to (if any). Components of this aspects have the following propoerties:

• ssid
• signalStrength
• networkStatus

15.1 The ssid property

The ssid property A DOMString that represents the SSID of a WiFi network.

15.2 The signalStrength property

The signalStrength property is an octet that represents the relative signal strength offered by the WiFi network (from 0 to 100, where 100 is full strength).

15.3 The networkStatus property

The networkStatus property A DOMString represented as one of the NetworkStates that indicates the state of a WiFi network.

16 Enums types

enum SwitchType {"ON", "OFF"};
enum NetworkStates {"connected", "available", "forbidden"};

Change Log

This specification was last updated on 30 April 2012. A complete list of changes are kept on our GIT repository.