System Info API Specification

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

• 1. Introduction
• 2. Scope
• 3. Use-Cases and Requirements
  • 3.1 Use-Cases
  • 3.2 Requirements
• 4. Security and privacy considerations
  • 4.1 Privacy considerations for implementers of the System Info API
  • 4.2 Privacy considerations for recipients of device System Info information
• 5. Conformance requirements
• 6. API Description
  • 6.1 Sysinfo interface
  • 6.2 Supported Channels
  • 6.3 SystemDataDescriptor interface
  • 6.4 SysinfoChannelDescriptor interface
  • 6.5 NetworkData interface
  • 6.6 ChargingData interface
  • 6.7 BatteryLevelData interface
  • 6.8 SignalStrengthData interface
  • 6.9 PhoneLanguageData interface
  • 6.10 BluetoothOnData interface
  • 6.11 ProductTypeData interface
  • 6.12 FirmwareVersionData interface
  • 6.13 Trigger
  • 6.14 Style
  • 6.15 Exception handling
• References

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.

 
    // 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");
    

 
    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);
    

    // 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);
    
    
    

    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);
    

    
    // 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

• The System Info API must allow an application to retrieve available channels and associated data in the hosting device.
• The System Info API must allow an application to read a specified channel data.
• The System Info API must allow an application to register to receive repeated updates of changes per channel.
• The System Info API must allow an application to stop or cancel an asynchronous request.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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