System Info API Specification

[23 April 2009]

Revision:
$Rev: 245 $

Abstract

This specification defines an API that provides scripted access to system information of a device.

Status of this document

Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.

Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.

Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.

Table of contents

Introduction

This section is non-normative.

The System Info API, also referred to as Sysinfo, defines a high-level interface to access system information associated with the hosting device, such as battery level, network status, phone language and Bluetooth status. In this specification such separate system information entities are referred to as channels.

The following code extract illustrates how to work with a System Info service to access system information of the device.

Example-1 for instantiating a service object to access the device system information.

 

    // Loads an instance of a Sysinfo interface identified by a service name

    // "device", an interface name "sysinfo" and an interface version "1" or later. 

    var mySysinfo = org.w3c.device.load("device", "sysinfo", "1");

    

NOTE: the namespace for the service interface loader is tentative.

Example of retrieving a list of supported channels and displaying their properties.

 

    var summary;

    // Retrieves a list of supported channels.

    var list = mySysinfo.getChannelList();     



    // Displays the supported channels by name and per each supported channel property their

    // name, valid data range and a human readable textual description.       

    for (var descriptor in list) {

        summary += "Channel " + descriptor.name + " has properties:\n";

        for (var name in descriptor.data) {

            summary += name + ": " + descriptor.data[name] + "\n";

        }

    }

    alert(summary);

    

Example of a one-shot retrieval of data associated with a "Network" channel.


    // Displays the "Network" channel data, such as the network status and cell ID.    

    function callback(data, status, transactionId) {

        var summary;

        for (var name in data) {

            summary += name + ": " + data[name] + "\n";            

        }

        alert(summary);

    }

    

    // Retrieves the properties of a "Network" channel as a one-shot asynchronous request.

    var transactionId = mySysinfo.getChannel("Network", callback);

    

    

    

Example of receiving repeated updates of the changes in the "Network" channel.


    var cellID;

    

    // Defines a callback function which is invoked on updates in the "Network" channel.

    function callback(data, status, transactionId) {

        // If the Cell ID has changed and the status is successful, assign the

        // new cell ID to global cellID variable and display a notification.

        if (cellID != data.cellID && status == 0) {

            cellID = data.cellID;

            alert("Cell ID changed to: " + cellID);

        }

    }

    

    mySysinfo.startChannel("Network", callback);

    

Example of stopping asynchronous updated from the "Network" channel.

    

    // Stops further notification from the "Network" channel.    

    mySysinfo.stopChannel("Network");

    

Scope

This section is non-normative.

This specification is limited to [define scope].

Use-Cases and Requirements

Use-Cases

To be written ...

Requirements

Security and privacy considerations

The API defined in this specification [define security and privacy considerations].

Privacy considerations for implementers of the System Info API

This section is a placeholder for a set of recommendations addressed to the implementers of the System Info API.

Conformance requirements

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

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in [WebIDL].

API Description

Sysinfo interface

The Sysinfo object can be used by scripts to programmatically interact with the system information of the device.

  interface Sysinfo {

    

    sequence<SystemChannelDescriptor>    getChannelList();

    

    SystemData getChannel(in DOMString channelName);

    int        getChannel(in DOMString channelName, in SystemCallback callback);

        

    int        startChannel(in DOMString channelName, in SystemCallback callback);

    int        startChannel(in DOMString channelName, in SystemCallback callback, in int trigger);    

    

    void       stopChannel(in DOMString channelName);

    

    void       cancel(in int transactionId);

    

  };

        

  interface SystemCallback {

     void handleEvent(in SystemData systemData, 

                      in int status, 

                      in int transactionId);

  };

  

The getChannelList() method returns an array of SystemChannelDescriptor objects which represent supported channels.

The getChannel() method takes a channelName and a callback as arguments. For synchronous invocation, a SystemData object of a channel identified by the channelName must be returned. For asynchronous invocation, the method must immediately return a unique transactionId and asynchronous invoke the callback function with the transactionId, status and SystemData object as arguments.

Depending on the channel characteristics only synchronous or asynchronous invocation may be supported. Refer to Supported Channels for more information. The callback argument values undefined and null are valid for synchronous usage. Supported system channels and their characteristics can be programmatically retrieved using getChannelList() method.

A condition in which the getChannel() method is invoked with an unsupported or unknown channelName as an argument is currently unspecified. A proposal is to throw a NOT_SUPPORTED_ERR exception for synchronous invocation and pass a corresponding error code 3 in status argument for asynchronous invocation of the callback.

The startChannel() method takes two or more arguments. When called it must immediately return a transactionId. Whenever a change is detected in the requested channel the associated callback is invoked with the transactionId, status and SystemData object as arguments. If the trigger argument is specified the callback is invoked only if the channel value is less than the trigger value.

The transactionId returned by the startChannel() method should not be used associated with cancel() method. To stop asyncronous requests invoked by startChannel() the stopChannel() method with channelName argument must be used.

Is the transactionId attribute returned by the startChannel() method redundant? Should the return value be either of type void or of type DOMString and return the channelName which could be passed to stopChannel()?

The stopChannel() method takes the channelName as an argument and stops further asynchronous invocations of the callback associated with the channel.

The cancel() method takes the unique transactionId of the on going one-shot asynchronous request and stops it.

Supported Channels

The following channels are supported in System Info API. The support for synchronous and asynchronous operations associated with each channel vary depending on the method operating on the channel. The getChannelList() method may be used to programmatically retrieve this information.

Channel Name SystemData getChannel (Behavior) startChannel (Async)
Charging ChargingData interface Sync Yes
BatteryLevel BatteryLevelData interface Async Yes
Network NetworkData interface Async Yes
SignalStrength SignalStrengthData interface Async Yes
PhoneLanguage PhoneLanguageData interface Sync No
BluetoothOn BluetoothOnData interface Sync Yes
ProductType ProductTypeData interface Sync No
FirmwareVersion FirmwareVersionData interface Sync No

SystemDataDescriptor interface

SystemDataDescriptor objects are regular ECMAScript objects that have the following properties:

  interface SystemDataDescriptor { 

     readonly  attribute DOMString       name;

     readonly  attribute DOMString       range;

     readonly  attribute DOMString       description; 

  };  

The name is the name of the system data property such as batteryLevel, networkName and networkStatus.

The range represents the possible values for the system data property. For example, for batteryLevel it contains a value of type DOMString where minimum and maximum are separated by a hyphen (U+002D) character as in 0-100.

Consider breaking the lower and upper bounds of the range attribute into their own attributes (e.g. min and max) to ease parsing.

The description contains a textual description of the system data. For example, the description of the batteryLevel contains a text battery charge level percentage.

SystemChannelDescriptor interface

SystemChannelDescriptor objects are regular ECMAScript objects that have the following properties:

  interface SystemChannelDescriptor { 

     readonly  attribute DOMString                       name;

     readonly  attribute sequence<SystemDataDescriptor>  data;

     readonly  attribute sequence<DOMString>             style;

  };

  

The name is the name of the channel which is unique to the system. Refer to Channel Name in Supported Channels.

The data is an array of data descriptor(s) of the data associated with the channel. For example, a channel with a name of BatteryLevel contains a data object with an attribute batteryLevel.

The style describes the data retrieval behavior of the channel. Refer to Style section for detailed description on the usage of this attribute.

SystemData interface

The SystemData is specific to the channel that has been requested. Refer to SystemData in Supported Channels section for complete list channels and associated SystemData.

Consider adding a channelName attribute to all the interfaces inheriting SystemData to allow invoking stopChannel() method within the scope of the callback invoked by the startChannel() method.

NetworkData interface

  interface NetworkData { 

    readonly attribute DOMString    networkName;

    readonly attribute DOMString    networkStatus;

    readonly attribute DOMString    networkMode;

    readonly attribute DOMString    mobileCountryCode;

    readonly attribute DOMString    mobileNetworkCode;

    readonly attribute boolean      locationStatus;

    readonly attribute int          areaCode;

    readonly attribute int          cellID;

  };  

The networkName is the name of the network operator.

The networkStatus is the mobile equipment registration status. Below are possible network status constant values of type DOMString.

available
Represents a network that the device is allowed to register to.
current
Represents the currently registered network.
forbidden
Represents a network to which the device is forbidden to register to.

The networkMode is the mode of operation of the network. Below are possible network mode constant values of type DOMString.

gsm
Represents a GSM network
cdma
Represents a CDMA network.
wcdma
Represents a WCDMA network.

Need to provide information about data transfer capabilities of the network.

The mobileCountryCode contains a Mobile Country Code (MCC) [ITUE212] which uniquely identifies a particular subscriber and is stored on a (usually) removable SIM card. MCC is often used in combination with Mobile Network Code (MNC) [ITUE212] in order to uniquely identify a network operator.

The mobileNetworkCode contains a Mobile Network Code (MNC) which is often used in combination with Mobile Country Code (MCC) in order to uniquely identify a network operator.

The locationStatus is a boolean which specifies if the areaCode and cellID values are valid. The possible values are:

false
Indicates areaCode and cellID are undefined.
true
Indicates areaCode and cellID are valid.

The usefulness of the locationStatus flag is questionable as currently specified.

The areaCode contains a network operator specific location area code.

The cellID contains a network operator specific cellID.

ChargingData interface

  interface ChargingData { 

    readonly attribute boolean chargingStatus;

  };

  

The chargingStatus attribute indicates the device battery charging status.

false
Indicates the battery is not charging.
true
Indicates the battery is charging.

BatteryLevelData interface

  interface BatteryLevelData { 

    readonly attribute unsigned int batteryLevel;

  }; 

The batteryLevel attribute represents device battery strength in percentage.

SignalStrengthData interface

 interface SignalStrengthData { 

    readonly attribute unsigned int signalStrength;

  };

  

The signalStrength attribute represents the cellular network signal strength in percentage.

PhoneLanguageData interface

  interface PhoneLanguageData { 

    attribute DOMString phoneLanguage;

  };

  

The phoneLanguage attribute represents a current phone display language in format ISO 639-2 [ISO639] (language) and ISO 3166-1 [ISO3166] (country). For example, a valid value is en-GB where the language and the country codes are delimited by a hyphen (U+002D).

Need to use BCP47 language tags instead.

BluetoothOnData interface

  interface BluetoothOnData { 

    attribute DOMString btOn;

  }; 

The btOn is a boolean specifying if the bluetooth is switched on in the device.

false
Indicates the Bluetooth connectivity is switched off and is unavailable.
true
Indicates the Bluetooth connectivity is switched on and is available.

ProductTypeData interface

  interface ProductTypeData { 

    readonly attribute DOMString productType;

  };

  

The productType specifies the product type information.

FirmwareVersionData interface

  interface FirmwareVersionData { 

    readonly attribute DOMString firmwareVersion;

  };

  

The firmwareVersion specifies the firmware version information.

Trigger

The trigger attribute is only applicable to channels BatteryLevel and SignalStrength. When trigger is specified, the associated callback registered to listen to changes is invoked only if the channel data value goes below the specified trigger value. The defaults and lower and upper bounds are as follows:

BatteryLevel (%)
Default: 50
Minimum: 0
Maximum: 100
SignalStrength (%)
Default: (notifies whenever a change occurs)
Minimum: 0
Maximum: 100

Describe in Web IDL.

Style

The style property returned by the getChannelList() method for each channel describes the data retrieval behavior supported by the channel. It is an array comprising of four strings, the possible values for each are shown below. A null value at an index indicates not applicable. For example, if style[0] is null the channel does not support synchronous behavior.

  style: [ 

     "sync", 

     "async", 

     "oneshot", 

     "notification"

  ]

  

Associated with getChannel() method, a non-null value of style[0] indicates a synchronous operation is supported and a non-null value of style[1] that an asynchronous operation is supported.

Flags Callback API Signature
sync no getChannel(channelName)
sync and async optional getChannel(channelName) or getChannel(channel, callback)
async yes getChannel(channel, callback)

The oneshot (style[2]) and the notification strings (style[3]) of style indicate respectively whether invoking getChannel() and startChannel() methods are supported for a specific channel.

Describe in Web IDL.

Consider refactoring the style into an object whose property names refer to corresponding behaviors and values are of type boolean. This ensures future extensibility and is more convenient and less error prone to operate on.


    var style = {

        sync: false,

        async: true,

        oneshot: false,

        notification: true

    };

    

    if (style["async"]) {

        // Asynchronous operation is supported.

    }

    

Exception handling

On error, the APIs throw DeviceException with an informative error code. The DeviceException interface and error constants are defined in Appendix A.

References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels.
[WebIDL]
Web IDL.
[ITUE212]
List of Mobile Country or Geographical Area Codes (ITU E.212).
[ISO639]
Codes for the Representation of Names of Languages (ISO 639-2).
[ISO3166]
ISO 3166 code lists (ISO 3166-1).