This specification defines an API that provides scripted access to system information of a device.
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.
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");
This section is non-normative.
This specification is limited to [define scope].
To be written ...
The API defined in this specification [define security and privacy considerations].
This section is a placeholder for a set of recommendations addressed to the implementers of the System Info API.
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].
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.
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.
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.
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
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
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.
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.
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.
availablecurrentforbiddenThe networkMode
is the mode of operation of the network. Below are possible network mode
constant values of type DOMString.
gsmcdmawcdmaNeed 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:
falseareaCode and cellID are
undefined.trueareaCode 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.
interface ChargingData {
readonly attribute boolean chargingStatus;
};
The chargingStatus
attribute indicates the device battery charging status.
falsetrue interface BatteryLevelData {
readonly attribute unsigned int batteryLevel;
};
The batteryLevel
attribute represents device battery strength in percentage.
interface SignalStrengthData {
readonly attribute unsigned int signalStrength;
};
The signalStrength
attribute represents the cellular network signal strength in percentage.
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.
interface BluetoothOnData {
attribute DOMString btOn;
};
The btOn is
a boolean specifying if the bluetooth is switched on in the device.
falsetrue interface ProductTypeData {
readonly attribute DOMString productType;
};
The productType
specifies the product type information.
interface FirmwareVersionData {
readonly attribute DOMString firmwareVersion;
};
The firmwareVersion
specifies the firmware version information.
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 (%)500100SignalStrength (%)0100Describe in Web IDL.
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.
}
On error, the APIs throw DeviceException with an informative
error code. The DeviceException interface and error constants are
defined in Appendix A.