The System Information & Events API

A proposal for the Device API and Policy Working Group System Information and Events API.

Power

This power specification is a set of APIs that exposes available power sources such as: batteries, wall outlet, etc. It also expose if the device is on battery power and its charge level.

readonly attribute boolean usingExternalPowerSource

The usingExternalPowerSource attribute must be true if the device is plugged into an external power source. Otherwise, it must be false. If the correct value cannot be obtained, or if the device does not have an internal power source, an implementation MUST return true.

readonly attribute unsigned short powerLevel

The powerLevel attribute MUST indicate what percent of the internal power source remains. The maximum value is 100, the minimum value is 0. If the value cannot be obtained, or if the device does not have an internal power source, the attribute value must be 0.

readonly attribute unsigned int timeRemaining

The timeRemaining attribute should indicate the estimated time remaining (seconds) at the current rate before the system enters shutdown mode. If usingExternalPowerSource is true and rate is greater than or equal to 0, this value MUST be 0, meaning that there is essentially infinite time remaining. If usingExternalPowerSource is true and

rate

is less than 0 (indicating that even though the system is plugged into an external power source, the battery is still being drained),

timeRemainging

should be greater than 0.

long watchPowerSource(in PowerSourceCallback successCallback, [Optional] in PowerErrorCallback errorCallback)

The watchPowerSource() method takes one, two or three arguments. When called, it MUST immediately return and then asynchronously start a watch process defined as the following set of steps:

Acquire a new PowerSource object that reflects the delivery context's current power source. If successful, invoke the associated successCallback with a PowerSource object as an argument. If the attempt fails, and the method was invoked with a non-null errorCallback argument, this method MUST invoke the errorCallback with a PowerError object as an argument.

long watchPowerLevel(in PowerLevelCallback successCallback, [Optional] in PowerErrorCallback errorCallback, [Optional] in PowerLevelOptions options)

The watchPowerLevel() method takes one, two or three arguments. When called, it MUST immediately return and then asynchronously start a watch process defined as the following set of steps:

Acquire a new PowerLevel object. If successful, invoke the associated successCallback with PowerLevel object as an argument. If the attempt fails, and the method was invoked with a non-null errorCallback argument, the implementation MUST invoke the errorCallback with a PowerError object as an argument.
Invoke the appropriate callback with a new PowerLevel object every time the implementation determines that the power level of the hosting device has changed.

void clearWatch(in int watchId)

Both watchPowerLevel() and watchPowerSource() methods return an integer value that uniquely identifies the watch process. When the clearWatch() method is called with this identifier, the watch process MUST cease invoking any callbacks.

PowerLevelCallback

void handleEvent(in PowerLevel level): This function is supplied by a call to watchPowerLevel(). Use the parameter to retrieve information about system power level.

PowerSourceCallback

void handleEvent(in boolean usingExternalPowerSource): This function is supplied by a call to watchPowerSource(). Use the parameter to retrieve information about system power source.

PowerLevelOptions

attribute unsigned int sampleInterval: The sampleInterval attribute specifies in milliseconds how often the implementation SHOULD check to see if the power level has changed. While the specification allows the caller to sample at very small intervals, on many implementations, this may be wasteful because the battery device may update its level information at a frequency significantly below the sampleInterval. On implementations that are event driven, this value MAY be ignored. The caller should be aware that setting a value too small can adversely affect the battery life. The default value SHOULD be 10,000, or once every 10 seconds.
attribute unsigned int highThreshold: If the highThreshold is greater than zero, when system power level rises above the specified value, the PowerLevelCallback MUST be invoked with the crossedHighThreshold value of the PowerLevel parameter set to true. If the PowerLevelOptions object is not null, and the highThreshold value is 100 (default), the PowerLevelCallback MUST not be invoked with the crossedHighThreshold value set to true. The value must be greater or equal to 0, and no greater than 100.
attribute unsigned int lowThreshold: If the lowThreshold is less than 100, when the system power level falls below the specified value, the PowerLevelCallback MUST be invoked with the crossedLowThreshold value of the PowerLevel parameter set to true. If the PowerLevelOptions object is not null, and the lowThreshold value is 0 (default), the PowerLevelCallback MUST not be invoked with the crossedLowThreshold value set to true. The value MUST be greater than or equal to 0, and no greater than 100.

PowerLevel

readonly attribute unsigned short percentRemaining

The percentRemaining attribute should specify what percent of the device internal power remains. For implementations where the internal power source differentiates between the Design Maximum Capacity and the Current Maximum Capacity, the Current Maximum Capacity SHOULD be used. The maximum value MUST be 100; the minimum value MUST be 0, although that value MAY never be reported.

readonly attribute boolean crossedHighThreshold

When a PowerLevelCallback is invoked with a PowerLevel object whose crossedHighThreshold attribute set to true, the power level high threshold has been crossed. This threshold value is set in the PowerOptions parameter of a call to

watchPowerLevel()

. The crossedHighThreshold value MUST be false if any one of the following is true:

The PowerLevel object is obtained by directly accessing the Power.PowerLevel attribute;
The PowerLevelOption highThreshold value was either not set or set to 100 in a prior call to watchPowerLevel();
The current power level is not greater than the value specified by the PowerLevelOption highThreshold value specified in a prior call to watchPowerLevel();
The current power level is greater than the value specified by the PowerLevelOption highThreshold value specified in a prior call to watchPowerLevel() but the highThresholdHysteresis attribute in the PowerLevelOption was either not set or set to a value greater than the highThreshold;
The current power level is greater than the value specified by the PowerLevelOption highThreshold value in a prior call to watchPowerLevel(), but the high threshold event has already been called once, and the system power level has not yet dropped below the value specified by the highThresholdHysteresis attribute in the PowerLevelOption.

readonly attribute boolean crossedLowThreshold

When a PowerLevelCallback is invoked with a PowerLevel object whose crossedLowThreshold attribute set to true, the power level low threshold has been crossed. This threshold value MUST be set in the PowerOptions parameter of a prior call to watchPowerLevel(). The crossedLowThreshold value will be false if any one of the following is true:

The PowerLevel object is obtained by directly accessing the Power.PowerLevel attribute;
The PowerLevelOption lowThreshold value was either not set or set 0 in a prior call to watchPowerLevel();
The current power level is not less than the value specified by the PowerLevelOption lowThreshold value in a prior call to watchPowerLevel();
The current power level is less than the value specified by the PowerLevelOption lowThreshold value in a prior call to watchPowerLevel() but the lowThresholdHysteresis attribute in the PowerLevelOption was either not set or set to a value less than the lowThreshold;
The current power level is less than the value specified by the PowerLevelOption lowThreshold value in a prior call to watchPowerLevel(), but the low threshold event has already been called once, and the system power level has not yet risen above the value specified by the lowThresholdHysteresis attribute in the PowerLevelOption.

PowerError

readonly attribute unsigned short UNKNOWN_ERROR: UNKNOWN_ERROR (numeric value 0): The implementation failed to retrieve either power source or power level information for an unknown reason.
readonly attribute unsigned short PERMISSION_DENIED: PERMISSION_DENIED (numerice value 1): The implementation failed to retrieve either power source or power level information because the application context does not have permission to use the Platform API.
readonly attribute unsigned short INFORMATION_UNAVAILABLE: INFORMATION_UNAVAILABLE (numeric value 2): The implementation failed to retrieve power information because the information was unavailable. For example, this error would be raised if the system currently does not have an internal power source, or if the system does provide this information.
readonly attribute unsigned short TIMEOUT: TIMEOUT (numeric value 3): The specified maximum length of time has elapsed before the implementation could successfully acquire power information.
readonly attribute unsigned short INVALID_VALUE: INVALID_VALUE (numeric value 4): The implementation failed to retrieve power source or power level information because one or more of the values in the PowerLevelOptions or PowerSourceOptions parameters of the watchPowerLevel() or watchPowerSource() calls was invalid. For example, if the PowerLevelOptions highThreshold attribute is set to a value greater than 100, the PowerErrorCallback MUST be invoked with the PowerError code attribute set with a value of INVALID_VALUE (4).
readonly attribute unsigned short code: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

CPU

This section defines a set of APIs that expose CPU information such as: utilization, frequency, brand, etc.

readonly attribute unsigned int numLogicalProcessors

The numLogicalProcessors attribute MUST indicate how many threads can run concurrently on the device. The minimum value is 1.

readonly attribute unsigned int currentFrequency

The currentFrequency attribute MUST indicate the current frequency of the CPU in Megahertz (MHz). On devices that have multiple CPUs that can run at different frequencies, this attribute SHOULD reflect the average frequency of the CPUs.

readonly attribute unsigned int maximumFrequency

The maximumFrequency attribute MUST indicate the maximum frequency for the CPU(s) in Megahertz (MHz). On devices that have mutilple CPUs that have different maximum frequencies, this attribute SHOULD reflect the maximum value.

readonly attribute unsigned short usage

The usage attribute MUST indicate at the time of retrieval what percentage of the total CPU resources are in use. If the device has more than one CPU, this attribute MUST be the average usage of all CPUs on the system. The maximum value is 100; the minimum value is 0.

readonly attribute CpuArchitecture architecture

The architecture of the CPU.

readonly attribute string brand

The brand attribute MUST include information about both the manufacturer and the model number. It MAY contain information identifying the supported instruction set.

long watchCpuUsage(in CpuUsageCallback successCallback, [Optional] in CpuUsageErrorCallback errorCallback, [Optional] in CpuUsageOptions options)

The watchCpuUsage function allows callers to monitor a delivery context's CPU utilization and takes one, two or three parameters. When called, it must immediately return and then asynchronously start a watch process defined by the following set of steps:

Acquire a new CpuUsage object that reflects the delivery context's current CPU utilization. If successful, invoke the associated successCallback with the CpuUsage object as an argument depending on the values specified in the CpuUsageOptions parameter. If the attempt fails, and the method was invoked with a non-null errorCallback argument, this method MUST invoke the errorCallback with a CpuUsageError object as an argument.
Invoke the appropriate callback with a new CpuUsage object every time the implementation determines that the CPU utilization of the deliver context has changed in the manner specified by the CpuUsageOptions parameter.

void clearWatch(in int watchId)

The watchCpuUsage() method returns an integer value that uniquely identifies the watch process. When the clearWatch() method is called with this identifier, the watch process MUST stop monitoring device CPU utilization and MUST cease invoking any callbacks.

CpuUsageCallback

void handleEvent(in CpuUsage usage): This function is supplied by a call to watchCpuUsage(). Use the parameter to retrieve information about system cpu utilization.

CpuUsageErrorCallback

void handleEvent(in CPUUsageError error): This function is supplied by a call to watchCpuUsage(). Use the parameter to retrieve information about the error that occured while the implementation attempted to obtain Cpu Utilization information.

CpuUsageOptions

attribute unsigned short highThreshold: The highThreshold attribute allows the caller to specify that the implementation MUST only invoke the CpuUsageCallback when the device CPU utilization rises above the value specified. The maximum value is 100, the minimum value is 0. The default value is 100, meaning that the CpuUsageCallback MUST NOT be invoked with the CpuUsage crossedHighThreshold attribute set to true.
attribute unsigned short lowThreshold: The lowThreshold attribute allows the caller to specify that the implementation MUST only invoke the CpuUsageCallback when the device CPU utilization falls below the value specified. The maximum value is 100, the minimum value is 0. The default value is 0, meaning that the CpuUsageCallback MUST NOT be invoked with the CpuUsage crossedLowThreshold attribute set to true.
attribute unsigned short highThresholdSampleCount: The highThresholdSampleCount attribute allows the caller to specify how many consecutive samples must be taken above the value specified by highThreshold before the CpuUsageCallback function is invoked with the crossedHighThreshold attribute set to true. For example, If the value is 1, the CpuUsageCallback function MUST be invoked with the crossedHighThreshold attribute set to true every time the implementation samples the CPU utilization. If the value is 2, the CpuUsageCallback function MUST be invoked with the crossedHighThreshold attribute set to true only if the implementation collects two consecutive samples that are greater than the value specified by the highThreshold attribute. The default value is 1, which is also the minimum value.
attribute unsigned short lowThresholdSampleCount: The lowThresholdSampleCount attribute allows the caller to specify how many consecutive samples must be taken below the value specified by lowThreshold before the CpuUsageCallback function is invoked with the crossedLowThreshold attribute set to true. For example, If the value is 1, the CpuUsageCallback function MUST be invoked with the crossedLowThreshold attribute set to true every time the implementation samples the CPU utilization. If the value is 2, the CpuUsageCallback function must be invoked with the crossedLowThreshold attribute set to true only if the implementation collects two consecutive samples that are greater than the value specified by the lowThreshold attribute. The default value is 1, which is also the minimum value.
attribute unsigned int sampleInterval: The sampleInterval attribute is a hint to the implementation regarding how often (in milliseconds) it SHOULD sample Cpu utilization. An implementation SHOULD sample at the suggested rate, but MAY chose to ignore values that are too small and which are likely to hamper system performance. If no highThreshold or lowThreshold values are specified, the implementation MUST invoke the CpuUsageCallback each time CPU utilization is sampled. The default sample interval is 2000, or once every two seconds.
attribute int timeout: The timeout attribute specifies how long (in milliseconds) an implementation SHOULD attempt to measure CPU utilization before invoking the CpuUsageErrorCallback with the TIMEOUT error code. The default value is 5000, or five seconds.

CpuUsage

readonly attribute unsigned short usage

The usage attribute MUST indicate what percentage of the total CPU resources are in use when the CpuUsageCallback method is invoked. If the device has more than one CPU, this attribute MUST be the average usage of all CPUs on the system. The maximum value is 100; the minimum value is 0.

readonly attribute DOMTimeStamp timestamp

The timestamp attribute MUST indicate when the Cpu usage value was obtained.

readonly attribute boolean crossedHighThreshold

When a CpuUsageCallback is invoked with a CpuUsage object whose crossedHighThreshold attribute set to true, the cpu usage high threshold has been crossed. This threshold value is set in the CpuUsageOptions parameter of a call to

watchCpuUsage()

. The crossedHighThreshold value MUST be false if any one of the following is true:

The CpuUsageOption highThreshold value was either not set or set to 100 in a prior call to watchCpuUsage(); or
The current usage is not greater than the value specified by the CpuUsageOption highThreshold value specified in a prior call to watchCpuUsage().

readonly attribute boolean crossedLowThreshold

When a CpuUsageCallback is invoked with a CpuUsage object whose crossedLowThreshold attribute set to true, the cpu utilization low threshold has been crossed. This threshold value MUST be set in the CpuUsageOptions parameter of a prior call to


					watchCpuUsage()

. The crossedLowThreshold value MUST be false if any one of the following is true:

The CpuUsageOption lowThreshold value was either not set or set 0 in a prior call to watchCpuUsage(); or
The current cpu utilization is not less than the value specified by the CpuUsageOption lowThreshold value in a prior call to watchCpuUsage().

CpuUsageError

readonly attribute unsigned short UNKNOWN_ERROR: UNKNOWN_ERROR (numeric value 0): The implementation failed to retrieve Cpu usage information for an unknown reason.
readonly attribute unsigned short PERMISSION_DENIED: PERMISSION_DENIED (numerice value 1): The implementation failed to retrieve Cpu usage information because the application context does not have permission to use the Platform API.
readonly attribute unsigned short INFORMATION_UNAVAILABLE: INFORMATION_UNAVAILABLE (numeric value 2): The implementation failed to retrieve Cpu usage information because the information was unavailable.
readonly attribute unsigned short TIMEOUT: TIMEOUT (numeric value 3): The specified maximum length of time has elapsed before the implementation could successfully acquire Cpu usage information.
readonly attribute unsigned short INVALID_VALUE: INVALID_VALUE (numeric value 4): The implementation failed to retrieve CPU usage information because one or more of the values in the CpuUsageOptions parameter of the watchCpuUsage() call was invalid. For example, if the CpuUsageOptions highThreshold attribute is set to a value greater than 100, the CpuErrorCallback must be invoked with the CpuUsageError code attribute set with a value of INVALID_VALUE (4).
readonly attribute unsigned short code: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

CpuArchitecture

From BONDI.

readonly attribute unsigned short ARCH_UNKNOWN: UNKNOWN_ARCH (numeric value 0): The Cpu architecture is unknown.
readonly attribute unsigned short ARCH_I386: ARCH_I386 (numerice value 1): The CPU architecture is based on the Intel(R) 386 instruction set.
readonly attribute unsigned short ARCH_I586: ARCH_I586 (numerice value 2): The CPU architecture is based on the Intel(R) 586 instruction set.
readonly attribute unsigned short ARCH_x86-64: ARCH_x86-64 (numerice value 3): The CPU architecture is based on the x86 64-bit architecture.
readonly attribute unsigned short ARCH_ARM: ARCH_ARM (numerice value 4): The CPU is an ARM processor.
readonly attribute unsigned short architecture: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

Display

The window.screen object already exposes width, height, availWidth, availHeight, and colorDepth properties. This object could expose that information as well so that there would be a single object through which all the info is available, or else this object could expose only those objects that are not available on window.screen.

readonly attribute unsigned int dotsPerInch

Returns the number of dots per inch on the display. If it cannot be detected, returns zero.

readonly attribute boolean screenBlank

Returns true if the screen is blank or if screen saver is active; false if otherwise.

readonly attribute DisplayOrientation currentOrientation

Returns a DisplayOrientation object that indicates the orientation of the current display.

readonly attribute sequence<DisplayOrientation> supportedOrientations

The orientations that this device supports.

readonly attribute int brightness

The brightness of the display as a percentage. If brightness cannot be determined, this value will be less than zero.

int watchOrientation ( in OrientationChangedCallback successCallback, [Optional] in DisplayErrorCallback errorCallback)

The watchOrientation() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the display device's orientation.
Invoke the appropriate callback with a new DisplayOrientation object every time the implementation determines that the orientation of the primary display has changed.

This method returns an integer value that uniquely identifies the watch process. When the clearWatch() method is called with this identifier, the watch process must stop acquiring any new position fixes and must cease invoking any callbacks. When this value is used in a call to updatePosition(), the watch process SHOULD update the position information that it is using in its orientation caluculations.

int watchColorDepth ( in ColorDepthChangedCallback successCallback, [Optional] in DisplayErrorCallback errorCallback)

The watchColorDepth() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the display device's color depth.
Invoke the appropriate callback with the new color depth every time the implementation determines that the color depth of the primary display has changed.

int watchResolution ( in ResolutionChangedCallback successCallback, [Optional] in DisplayErrorCallback errorCallback)

The watchResolution() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the display device's resolution.
Invoke the appropriate callback with the new resolution every time the implementation determines that the resolution of the primary display has changed.

int watchBrightness ( in BrightnessChangedCallback successCallback, [Optional] in DisplayErrorCallback errorCallback)

The watchBrightness() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the display device's brightness.
Invoke the appropriate callback with the new brightness every time the implementation determines that the brightness of the primary display has changed.

void clearWatch ( in int watchId )

When this method is called, the implementation MUST stop calling the successCallback and errorCallback associated with the watchId.

DisplayOrientation

readonly attribute unsigned short orientation: The display orientation from the values listed in this object.
readonly attribute unsigned short ORIENTATION_LANDSCAPE: The display orientation is landscape.
readonly attribute unsigned short ORIENTATION_PORTRAIT: The display orientation is portrait.
readonly attribute unsigned short ORIENTATION_INVERTED_LANDSCAPE: The display orientation is inverted landscape.
readonly attribute unsigned short ORIENTATION_INVERTED_PORTRAIT: The display orientation is inverted portrait.
readonly attribute DOMTimestamp timestamp: The time at which the display orientation was determined.

OrientationChangedCallback

void handleEvent(in DisplayOrientation displayOrientation): Called whenever the implementation detects that the orientation of the display has changed.

ColorDepthChangedCallback

void handleEvent(in unsigned int colorDepth): Called whenever the implementation detects that the color depth of the display has changed. Zero if unable to determine.

ResolutionChangedCallback

void handleEvent(in int resolution): Called whenever the implementation detects that the resolution of the display has changed. Zero if unable to determine.

BrightnessChangedCallback

void handleEvent(in int displayBrightness): Called whenever the implementation detects that the brightness of the display has changed. If displayBrightness is zero, the screen is blank.

DisplayErrorCallback

void handleEvent(in DisplayError displayError): Called whenever the implementation encounters an error while monitoring the display.

DisplayError

readonly attribute unsigned short UNKNOWN_ERROR: The implementation was unable to monitor the display due to an error not covered by the definition of any other error code in this interface.
readonly attribute unsigned short PERMISSION_DENIED: The implementation was unable to monitor the display because the application origin does not have permission to use this API.
readonly attribute unsigned short NO_DISPLAY_DEVICE: The implementation was unable to monitor the display orientation because there is no display device.
readonly attribute unsigned short code: Indicates the reason the implementation failed monitor the display.
readonly attribute DOMTimestamp timestamp: The time at which the error occured.

Connection

The Connection Interface can be used by applications to determine the network status of the device, the device's ability to connect to services over the current network, and the quality of the existing network connection(s). This API could specify a lot more information than it does. Attempts have been made to limit the specification to datum that, according to the Device API WG, have highly probable use cases.

For a more extensive sample of the kinds of connection/network related information that could be exposed, see the Moblin Platform Awareness Service. See also the BONDI 1.0 vocabulary and [[DCONTOLOGY]].

The range of information that could be provided by this API will continue to change as network technology evolves and paradigm shifts expose use cases for additional information and events.

readonly attribute NetworkBearer currentNetworkBearer

The current network bearer.

readonly attribute NetworkBearer defaultNetworkBearer

The default network bearer.

readonly attribute NetworkBearer preferredNetworkBearer

The preferrred network bearer.

readonly attribute sequence<NetworkBearer> availableNetworkBearers

The list network bearers that are currently available.

readonly attribute sequence<NetworkBearer> supportedNetworkBearers

The list of network bearers that the device supports.

readonly attribute boolean connected

If the system has at least one valid network connection, this attribute MUST be true. For a network connection to be valid, the currentNetworkBearer MUST be valid, and MUST have a valid IP address that allows it to communicate with other devices on the network. If the currentNetworkBearer is null, or if it does not have a valid IP Address, this attribute MUST be false.

boolean isReachable(in DOMString uriDestination, [Optional] in unsigned int timeout, [Optional] in unsigned int retryCount)

Returns true if the Uniform Resource Identifier (URI)


			uriDestination

is reachable within the timeout and

retryCount

. If no timeout or retryCount values are provided, the system default timeout will be used, and only one attempt to reach the URI will be made. If both timeout and retryCount are provided, this method could take up to timeout x retryCount milliseconds to return.

uriDestination MUST be in the form of:

uriDestination = protocol + "://" + host + [":"+port] + ["/"+virtual_dir]

protocol = "tcp" | "ftp" | "http" | "https" | "icmp"

port is required for "tcp"; It is optional for the others. virtual_dir only applies to "http" and "https".

host = IPAddress | HostName

An implementation SHOULD attempt to use the device's default proxy settings for HTTP, HTTPS, and FTP.

int getLatency(in DOMString uriDestination, [Optional] in unsigned int timeout, [Optional] in unsigned int retryCount)

Returns the latency to uriDestination in milliseconds. If no timeout is provided, the system default timeout will be used. If no retryCount value is provided, only one attempt will be made to reach uriDestination. If both timeout and retryCount are provided, this method could take up to timeout x retryCount milliseconds to return.

uriDestination MUST be in the form of:

uriDestination = protocol + "://" + host + [":"+port] + ["/"+virtual_dir]

protocol = "tcp" | "ftp" | "http" | "https" | "icmp"

port is required for "tcp"; It is optional for the others. virtual_dir only applies to "http" and "https".

host = IPAddress | HostName

An implementation SHOULD attempt to use the device's default proxy settings for HTTP, HTTPS, and FTP.

long watchServiceChange(in DOMString uriDestination, in ServiceChangeCallback changeCallback, [Optional] in ServiceChangeErrorCallback errorCallback, [Optional] in ServiceChangeOptions options)

The watchServiceChange() function takes two, three or four arguments.

uriDestination MUST be in the form of:

uriDestination = protocol + "://" + host + [":"+port] + ["/"+virtual_dir]

protocol = "tcp" | "ftp" | "http" | "https" | "icmp"

port is required for "tcp"; It is optional for the others. virtual_dir only applies to "http" and "https".

host = IPAddress | HostName

An implementation SHOULD attempt to use the device's default proxy settings for HTTP, HTTPS, and FTP. When called, watchServiceChange() MUST immediately return and then asynchronously start a watch process defined as the following set of steps:

Attempt to determine whether the service specified in uriDestination is reachable or not.

If the service is available, immediately invoke changeCallback with the ServiceChange available attribute set to true.
If the service is not available, immediately invoke changeCallback with the ServiceChange available attribute set to false.
If the attempt fails, and the method was invoked with a non-null errorCallback argument, invoke the errorCallback with a ServiceChangeError object as an argument.

Continue to monitor the availability of uriDestination and invoke the changeCallback whenever the availability changes state.
If an error occurs, invoke the errorCallback if it was provided.

long watchNetworkChange(in NetworkChangeCallback changeCallback, [Optional] in NetworkChangeErrorCallback errorCallback, [Optional] in NetworkChangeOptions options)

The watchNetworkChange() function takes one, two, or three arguments. When called, watchNetworkChange() MUST immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the network resources specified in the NetworkChangeOptions object.
When the specififed network resources change, invoke the NetworkChangeCallback with the appropriate flag set in the NetworkChange parameter to indicate what change occured.
If the monitoring fails at any point, and the method was invoked with a non-null errorCallback argument, invoke the errorCallback with a NetworkChangeError object as an argument.

void clearWatch(in int watchId)

The watchServiceChange() and watchNetworkChange() methodw return an integer value that uniquely identifies a watch process. When the clearWatch() method is called with this identifier, the associated watch process MUST stop monitoring network or service availability changes and MUST cease invoking any callbacks.

NetworkBearer

readonly attribute NetworkTechnology networkTechnology

This attribute indicates the network technology in use on a network. The value of NetworkTechnology technology attribute determines what additional attributes from sub-classes are valid. For example, if the NetworkTechnology technology value is GPRS, because a GPRS network is a CellularNetwork, attributes from Network, WirelessNetwork, PLMNetwork, and CellularNetwork will all be valid because of inheritance.

From [[DCONTOLOGY]] and BONDI.

NOTE: [[DCONTOLOGY]] has an additional operation band attribute that is associated with networkTechnology, but I have a difficult time envisioning a scenario in which an application would actually want that data.

readonly attribute Network network

NOTE: does this mean that the network bearer could be a wired network? Then does there need to be an APN?

readonly attribute DOMString ipAddress

The IP Address assigned to the device by the network bearer. An implementation SHOULD support both IP4 and IP6.

readonly attribute DOMString apn

The Access Point Name associated to a network bearer.

readonly attribute NetworkBearerTechnology bearerTechnology

NOTE: I really don't understand what this is. How is this different than the NetworkTechnology? In the DCCI ontology, the NetworkBearerTechnology aspect is simply an ID and a name. It also provides access to the max, min and typical upload and download bandwidth info. With my rudimentary understanding, I don't know that info couldn't be rolled directly into the NetworkBearer object.

readonly attribute unsigned int currentDownloadBandwidth

This property represents the current download bandwidth offered by a network bearer measured in Kbits/s. If the NetworkBearer object is not the currentNetworkBearer, this value SHOULD be 0.

readonly attribute unsigned int currentUploadBandwidth

This property represents the current upload bandwidth offered by a network bearer measured in Kbits/s. If the NetworkBearer object is not the currentNetworkBearer, this value SHOULD be 0.

readonly attribute unsigned int minDownloadBandwidth

This property represents the min download bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute unsigned int minUploadBandwidth

This property represents the min upload bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute unsigned int maxDownloadBandwidth

This property represents the max download bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute unsigned int maxUploadBandwidth

This property represents the max upload bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute unsigned int typicalDownloadBandwidth

This property represents the typical download bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute unsigned int typicalUploadBandwidth

This property represents the typical upload bandwidth offered by a network bearer measured in Kbits/s.

readonly attribute HttpProxy proxy

Either a transparent or non-transparent HTTP proxy.

NOTE: The DCCI ontology has this, but I don't know if it is necessary.

Network

The DeliveryContext and BONDI ontologies have a slightly different Network heirarchy.

readonly attribute NetworkStatus networkStatus: This property indicates the current status of the WirelessNetwork.
readonly attribute boolean supportsRemoteManagement: This property indicates that the network interface support remote management capabilities.

WiredNetwork

readonly attribute int linkSpeed: The link speed in Kilobits/second (Kbps).
readonly attribute boolean fullDuplex: true if the connection is full duplex; otherwise, false.

WirelessNetwork

readonly attribute unsigned int signalStrength: This property indicates the relative (from 0 to 100) signal strength offered by a wireless network in this Context.
BONDI has this attribute in the domain of CellularNetwork and WifiNetwork. [[DCONTOLOGY]] has it in the domain of Network. It doesn't really make sense in the WiredNetwork domain.

WifiNetwork

readonly attribute DOMString SSID: The Service Set Identifier of a WiFi Network. (From [[DCONTOLOGY]] and BONDI.)
readonly attribute EncryptionMode encryptionMode: The Service Set Identifier of a WiFi Network. (From BONDI.)

PLMNetwork

Public Land Mobile Network - A public land mobile network (PLMN) is a network that is established and operated by an administration or by a recognized operating agency (ROA) for the specific purpose of providing land mobile telecommunications services to the public.

NOTE: Right now, there is only one sub-class of PLMNetwork: CellularNetwork. Should the two be combined, or will there be other PLMNetwork classes that need definition? WiMAX?

readonly attribute DOMString mcc: Mobile Country Code - This property identifies univoquely the country of a mobile network. (From [[DCONTOLOGY]] and BONDI.)
readonly attribute DOMString mnc: Mobile Network Code - A Mobile Network Code (MNC) is used in combination with a Mobile Country Code (MCC) (also known as a "MCC / MNC tuple") to uniquely identify a mobile phone operator/carrier using the GSM, CDMA, iDEN, TETRA and UMTS public land mobile networks and some satellite mobile networks. (From [[DCONTOLOGY]] and BONDI.)
readonly attribute DOMString operatorName: The PLMN operator name. (From BONDI.)
NOTE: I'm not sure this is nessary as the mcc/mnc seems to accomplish the same purpose.

CellularNetwork

readonly attribute boolean isInRoaming: (From BONDI.)
readonly attribute DOMString cellId: Cell Identifier - The id of the cell to which the device is interacting with in the mobile network. (From [[DCONTOLOGY]] and BONDI.)

NetworkTechnology

The network's communication/connection technology. (Values taken from BONDI.)

NOTE: This list is going to change before the WG complete's it's task because the technology simply continues to evolve. Encapsulating the values in an object will allow the API to not change even if the range of potential values grows.

readonly attribute unsigned short UNKNOWN: Numeric value 0. Unable to determine the network technology for an unknown reason.
readonly attribute unsigned short NONE: Numeric value 1. No connection technology.
readonly attribute unsigned short Protocol802_3: Indicates that the network technology is protocol 802.3, otherwise known as ethernet. Use the NetworkBearer bandwidth addributes to determine the link speed.
The associated Network object is a WiredNetwork object.
readonly attribute unsigned short Protocol802_11a: Indicates that the network technology is protocol 802.11a.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short Protocol802_11b: Indicates that the network technology is protocol 802.11b.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short Protocol802_11g: Indicates that the network technology is protocol 802.11g.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short Protocol802_11n: Indicates that the network technology is protocol 802.11n.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short Protocol802_11k: Indicates that the network technology is protocol 802.11k.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short Protocol802_11e: Indicates that the network technology is protocol 802.11e.
The associated Network object is a WirelessNetwork object.
readonly attribute unsigned short GSM: Global System for Mobile communications.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short GPRS: General Packet Radio Service.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short EDGE: Enhanced Data Rates for GSM Evolution.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short CDMA: Code Division Multiple Access.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short WiMAX: Worldwide Interoperability for Microwave Access.
The associated Network object is a CellularNetwork object. NOTE: I'm not sure this is accurate. Do WiMAX connections have cellId and roaming concepts?
readonly attribute unsigned short iDEN: Integrated Digital Enhanced Network.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short TETRA: Terrestrial Trunked Radio.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short UMTS: Universal Mobile Telecommunications System. Otherwise known as 3G.
The associated Network object is a CellularNetwork object.
readonly attribute unsigned short technology: The technology attribute SHOULD contain one of the values defined in this specification. An implementation MAY define additional status codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an string message describing the network technology. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

NetworkStatus

Values taken from BONDI.

readonly attribute unsigned short UNKNOWN: UNKNOWN (numeric value 0): The implementation failed to retrieve information about network changs for an unknown reason.
readonly attribute unsigned short CONNECTED: Numeric value 1. The modem has acquired normal service and can use all available features
readonly attribute unsigned short EMERGENCY: Numeric value 2. Full service is not available but there is coverage permitting 911 emergency voice calls. The reasons full service is not available vary and can include: security lock, account activation, and others.
readonly attribute unsigned short NO_SERVICE: Numeric value 3. The modem has not acquired service, or the modem is security locked preventing service.
readonly attribute unsigned short ACCESS_DIFFICULTY: Numeric value 4. The network reports this fault. The modem is unable to register. The user should check their signal strength or contact their carrier.
readonly attribute unsigned short FORBIDDEN_PLMN: Numeric value 5. The network indicates that you do not have permission to use the public land mobile network.
readonly attribute unsigned short FORBIDDEN_AREA: Numeric value 6. The modem is in a geographic area where use of the service is not permitted.
readonly attribute unsigned short FORBIDDEN_ROAMING: Numeric value 7. The modem is not in its home coverage area and is not permitted to roam in the current coverage area.
readonly attribute unsigned short ILLEGAL_MOB_STATION: Numeric value 8. The user's account is not permitted on the network.
readonly attribute unsigned short ILLEGAL_MOB_EQUIP: Numeric value 9. The modem is not permitted on the network, possibly for regulatory reasons.
readonly attribute unsigned short UNKNOWN_IMSI: Numeric value 10. The SIM Subscriber identification module. Applies to GSM Global system for mobile communications. Usually refers to the European standard GSM operating on 900 MHz and 1800 MHz bands, but in North America refers to the 1900 MHz band. networks. Card's identifier is unrecognized (or disqualified) by carrier.
readonly attribute unsigned short AUTHENTICATION_FAILURE: Numeric value 11. The user name and/or password associated with the account profile failed to authenticate.
readonly attribute unsigned short GPRS_FAILED: Numeric value 12. GPRS service is not available.
readonly attribute unsigned short ANALOG: Numeric value 13. In analog service.
readonly attribute unsigned short DIGITAL: Numeric value 14. In digital service.
readonly attribute unsigned short AVAILABLE: Numeric value 15. The service is available, but is not connected.
readonly attribute unsigned short ADAPTER_DISABLED_SOFTWARE: Numeric value 16. The adapter or radio on the device that communicates with this network has been disabled in the software layer.
readonly attribute unsigned short ADAPTER_DISABLED_HARDWARE: Numeric value 17. The adapter or radio on the device that communicates with this network has been disabled in the hardware layer.
readonly attribute unsigned short status: The status attribute SHOULD contain one of the values defined in this specification. An implementation MAY define additional status codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the status. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

EncryptionMode

The WiFi network's encryption mode. (Values taken from BONDI.)

readonly attribute unsigned short UNKNOWN: Numeric value 0. Unable to determine the WiFi network encryption mode for an unknown reason.
readonly attribute unsigned short NONE: Indicates that there is no encryption on the WiFi network.
readonly attribute unsigned short NO_WEP: Indicates that there is no Wep on the encryption mode.
NOTE: I'm not sure if this isn't the same as NONE.
readonly attribute unsigned short WEP_40: Indicates that the encryption mode is 40-bit WEP (Wired equivalent privacy) protocol.
readonly attribute unsigned short WEP_104: Indicates that the encryption mode is 104-bit WEP (Wired equivalent privacy).
readonly attribute unsigned short CKIP_40: Indicates that the encryption mode is 40-bit CKIP (Cisco Key Integrity Protocol).
readonly attribute unsigned short CKIP_104: Indicates that the encryption mode is 104-bit CKIP (Cisco Key Integrity Protocol).
readonly attribute unsigned short TKIP: Indicates that the encryption mode is TKIP (Temporal Key Integrity Protocol).
readonly attribute unsigned short CCMP: Indicates that the encryption mode is CCMP (Counter Mode with Cipher Block Chaining Message Authentication Code Protocol).
readonly attribute unsigned short AES_WRAP: Indicates that the Wifi network uses AES encryption key wrapping.
readonly attribute unsigned short mode: The mode attribute SHOULD contain one of the values defined in this specification. An implementation MAY define additional status codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an string message describing the network technology's encryptiono mode. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

ServiceChangeCallback

void handleEvent(in ServiceChange change): This function is supplied by a call to watchServiceChange(). Use the parameter to retrieve information about the visibility of a service.

ServiceChangeErrorCallback

void handleEvent(in ServiceChangeError error): This function is supplied by a call to watchServiceChange(). Use the parameter to retrieve information about an error that occured while the implementation attempted to determine the visibility of a service.

ServiceChangeOptions

attribute unsigned int sampleInterval: The sampleInterval attribute specifies in milliseconds how often the implementation SHOULD check to see if the device has accelerated. On implementations that are event driven, this value MAY be ignored. The caller should be aware that while lower values increase the reporting accuracy, they also adversely affect the device's battery life.
attribute unsigned int timeout: Allows the caller to specify the length of time that the implementation MUST attempt to reach the service before timing out. If the attempt times out, the service is deemed unavailable. If this attribute is not provided, the implementation MUST use the system default timeout.

NetworkChangeCallback

void handleEvent(in NetworkChange change): This function is supplied by a call to watchNetworkChange(). Use the parameter to retrieve information about network changes that the device detects.

NetworkChangeErrorCallback

void handleEvent(in NetworkChangeError error): This function is supplied by a call to watchNetworkChange(). Use the parameter to retrieve information about errors that occur while the implementation attempts to monitor network changes.

NetworkChangeOptions

attribute unsigned int sampleInterval: The sampleInterval attribute specifies in milliseconds how often the implementation SHOULD check to see if the the specified network resources have changed. On implementations that are event driven, this value MAY be ignored. The caller should be aware that while lower values increase the reporting accuracy, they also adversely affect the device's battery life. The default value SHOULD be 500, or twice every second.
attribute boolean watchIpAddress: When the implementation detects that the IpAddress(es) assigned to the device have changed, it MUST invoke the NetworkChangeCallback with the NetworkChange.ipAddressChanged attribute set to true. If this value is not specified, or if it is set to false, IP Addresses SHOULD not be monitored, and the implementation MUST NOT invoke the NetworkChangeCallback with the NetworkChange.ipAddressChanged attribute set to true.
attribute boolean watchRouteTable: When the implementation detects that the system route table has changed, it MUST invoke the NetworkChangeCallback with the NetworkChange.routeTableChanged attribute set to true. If this value is not specified, or if it is set to false, the system Route Table SHOULD not be monitored, and the implementation MUST NOT invoke the NetworkChangeCallback with the NetworkChange.routeTableChanged attribute set to true.
attribute boolean watchConnection: Invoke the NetworkChangeCallback when the device connection state changes. If all connections are lost, the NetworkChange.disconnected attribute will be true. If there were no connections and one was established, the NetworkChange.connected attribute will be true.
The default value is true, meaning that if NetworkChangeOptions parameter is not provided in the call to watchNetworkChanges(), the implementation will only watch connection changes.

ServiceChange

readonly attribute DOMTimestamp timestamp: The timestamp attribute MUST indicate when the change occured.
readonly attribute DOMString uriDestination: The URI that is being monitored.
readonly attribute boolean available: Indicates whether the service is available or not as a result of the state change.

NetworkChange

readonly attribute DOMTimestamp timestamp: The timestamp attribute MUST indicate when the change occured.
readonly attribute boolean IpAddressChanged: Indicates that the IP Address(es) assigned to the system changed.
readonly attribute boolean RouteTableChanged: Indicates that the system route table changed.
readonly attribute boolean connected: The change event was generated because the system had no network connections, and at least one has been established
readonly attribute boolean disconnected: The change event was generated because the system had at least one network connection, and it now has none.

ServiceChangeError

readonly attribute unsigned short UNKNOWN_ERROR: UNKNOWN_ERROR (numeric value 0): The implementation failed to retrieve information about service availability for an unknown reason.
readonly attribute unsigned short PERMISSION_DENIED: PERMISSION_DENIED (numerice value 1): The implementation failed to retrieve information about service availability because the application context does not have permission to use the Platform API.
readonly attribute unsigned short INFORMATION_UNAVAILABLE: INFORMATION_UNAVAILABLE (numeric value 2): The implementation failed to retrieve information about service availability because the information was unavailable.
readonly attribute unsigned short INVALID_PARAMETER: The implementation failed to retrieve information about service availability because one or more of the parameters in the watchMovement() call was invalid. For example, if the uriDestination is not a valid [[URI]], the ServiceChangeErrorCallback must be invoked with the ServiceChangeError.code attribute equal to INVALID_PARAMETER (3).
readonly attribute unsigned short code: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

NetworkChangeError

readonly attribute unsigned short UNKNOWN_ERROR: UNKNOWN_ERROR (numeric value 0): The implementation failed to retrieve information about network changs for an unknown reason.
readonly attribute unsigned short PERMISSION_DENIED: PERMISSION_DENIED (numerice value 1): The implementation failed to retrieve network change information because the application context does not have permission to use the Platform API.
readonly attribute unsigned short INFORMATION_UNAVAILABLE: INFORMATION_UNAVAILABLE (numeric value 2): The implementation failed to retrieve network change information because the information was unavailable.
readonly attribute unsigned short code: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

Thermal

A host device could have many thermometers associated with it. For example, an in-car device might have a thermometer that reports engine temperature, one that reports outside temperature one that reports the ambient temperature in the car, and another that reports the temperature of the CPU or other component on the device.

readonly attribute sequence <Thermometer> thermometers: The list of thermometers attached to the system.

Thermometer

readonly attribute ThermalTarget thermalTarget

Indicates the target that the thermometer is designed to measure.

readonly attribute DOMString Id

A string that uniquely identifies the thermometer on the system.

readonly attribute float temperature

The temperature in degrees Celsius.

long watchTemperature(in TemperatureChangeCallback changeCallback, [Optional] in TemperatureErrorCallback errorCallback, [Optional] in TemperatureChangeOptions options)

The watchTemperature() function takes one, two, or three arguments. When called, watchTemperature() MUST immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the ambient temperature.
When the temperature changes in a manner specified by the options parameter, invoke the TemperatureChangeCallback with the appropriate attribute set in the TemperatureChange parameter to indicate what change occured.
If the monitoring fails at any point, and the method was invoked with a non-null errorCallback argument, invoke the errorCallback with a TemperatureChangeError object as an argument.

void clearWatch(in long watchId)

The watchTemperature() method returns an integer value that uniquely identifies a watch process. When the clearWatch() method is called with this identifier, the associated watch process MUST stop monitoring temperature changes and MUST cease invoking any callbacks.

ThermalTarget

The thermal target is the object that the thermometer is designed to measure.

readonly attribute unsigned short UNKNOWN_TARGET: UNKNOWN_TARGET (numeric value 0): The implementation is unable to determine what the thermal target is.
readonly attribute unsigned short INTERNAL_COMPONENT: INTERNAL_COMPONENT (numerice value 1): The thermometer is deigned to measure and report the temperature of an internal system or device component such as the CPU.
readonly attribute unsigned short AMBIENT_ENVIRONMENT: AMBIENT_ENVIRONMENT (numeric value 2): The thermometer is deigned to measure and report the temperature of the host device's ambient environment.
readonly attribute unsigned short EXTERNAL_ENVIRONMENT: EXTERNAL_ENVIRONMENT (numeric value 3): The thermometer is deigned to measure and report the temperature of the external environment, e.g. the outside temperature.
readonly attribute unsigned short EXTERNAL_COMPONENT: EXTERNAL_COMPONENT (numeric value 4): The thermometer is deigned to measure and report the temperature of an external component such as a car engine.
readonly attribute unsigned short ANIMATE_BODY: ANIMATE_BODY (numeric value 5): The thermometer is deigned to measure and report the temperature of an external animate object such as a human body.
readonly attribute unsigned short code: The code attribute SHOULD contain one of the values defined in this specification. An implementation MAY define additional thermal targets, but MUST NOT use the numeric values defined here.
readonly attribute DOMString description: The description attribute MAY return more detail about the thermometer target.

TemperatureErrorCallback

void handleEvent(in TemperatureError error): If provided, this function MUST be called whenever the implementation is unable to retrieve temperature information as a result to a prior call to either getCurrentTemperature() or watchTemperature().

TemperatureChangeCallback

void handleEvent(in TemperatureChange temperature): This function MUST be called whenever the implementation successfully retrieves temperature information that matches the criteria specified in the TemperatureChangeOptions parameter of a prior call to watchTemperature() .

TemperatureChangeOptions

attribute unsigned int sampleInterval: The sampleInterval attribute specifies in milliseconds how often the implementation SHOULD check to see if the temperature has changed. On implementations that are event driven, this value MAY be ignored. The caller should be aware that setting a value too small can adversely affect the battery life. The default value SHOULD be 30,000, or once every 30 seconds.
attribute int timeout: The timeout attribute denotes the maximum length of time (expressed in milliseconds) that is allowed to pass from the call to watchTemperature() until the corresponding successCallback is invoked. If the implementation is unable to successfully acquire information about the temperature before the given timeout elapses, and no other errors have occurred in this interval, then the corresponding errorCallback MUST be invoked with a TemperatureError object whose code attribute is set to TIMEOUT. If the timeout attribute is negative or not specified, the implementation MUST never timeout and MUST never invoke the errorCallback with a TemperatureError object whose code attribute is set to TIMEOUT. If the timeout attribute is zero, the errorCallback MUST be invoked if power Level information is not available immediately.
attribute float highThreshold: If the highThreshold attribute is not null, when system temperature rises above the specified temperature (in Celsius), the TemperatureChangeCallback MUST be invoked with the crossedHighThreshold value of the TemperatureChange parameter set to true. If the TemperatureChangeOptions highThreshold attribute is null or not specified, TemperatureChangeCallback MUST NOT be invoked with the crossedHighThreshold value set to true.
attribute float lowThreshold: If the lowThreshold attribute is not null, when system temperature falls below the specified temperature (in Celsius), the TemperatureChangeCallback MUST be invoked with the crossedLowThreshold attribute of the TemperatureChange parameter set to true. If the TemperatureChangeOptions lowThreshold attribute is null or not specified, TemperatureChangeCallback MUST NOT be invoked with the crossedHighThreshold value set to true.

TemperatureChange

The TemperatureChange object inherits the timestamp and temperature attributes from Temperature.

readonly attribute boolean crossedHighThreshold: The ambient temperature has crossed the threshold specified in the TemperatureChangeOptions highThreshold attribute in a prior call to watchTemperature().
readonly attribute boolean crossedLowThreshold: The ambient temperature has crossed the threshold specified in the TemperatureChangeOptions lowThreshold attribute in a prior call to watchTemperature().
readonly attribute float temperature: The temperature in degrees Celsius.

TemperatureError

readonly attribute unsigned short UNKNOWN_ERROR: UNKNOWN_ERROR (numeric value 0): The implementation failed to retrieve temperature information for an unknown reason.
readonly attribute unsigned short PERMISSION_DENIED: PERMISSION_DENIED (numerice value 1): The implementation failed to retrieve temperature information because the application context does not have permission to use the Platform API.
readonly attribute unsigned short AMBIENT_ENVIRONMENT: AMBIENT_ENVIRONMENT (numeric value 2): The implementation failed to retrieve temperature information because the information was unavailable.
readonly attribute unsigned short code: The code attribute SHOULD contain one of the errors defined in this specification. An implementation MAY define additional error codes, but MUST NOT use the numeric values defined here.
readonly attribute DOMString message: The message attribute MAY return an error message describing the details of the error encountered. This attribute is primarily intended for debugging and developers SHOULD NOT use it directly in their application user interface.

Audio

This spec uses terminology found in the Wikipedia Comparison of Audio Codecs

readonly attribute AudioArch arch: Audio architecture information.
readonly attribute sequence AudioCodec codecs: Audio codecs on this device
readonly attribute sequence Speaker speakers: Speakers attached to this device
readonly attribute sequence LineOut linesout: Lines out
readonly attribute sequence Microphone mics: Speakers attached to this device
readonly attribute sequence LineIn linesin: Lines in

AudioArch

readonly attribute DOMString impName: Implementer name. Examples : "Logitech",

AudioCodec

readonly attribute DOMString impName: Implementation name. Examples : "Microsoft G.711", "LAME",
readonly attribute DOMString compFormat: Compression format name. Examples : "G.711", "MP3"
readonly attribute boolean encode: True if decode is supported
readonly attribute boolean decode: True encode is supported
readonly attribute boolean hwAccel: True if the codec includes hardware acceleration support. (QUESTION: does this make sense here?)

LineIn

readonly attribute unsigned int channel: common name for the line in. Example "line in" QUESTION: does this make sense here )

LineOut

readonly attribute unsigned int channel: common name for the line out. Example "line out" (QUESTION: does this make sense here )

Speaker

readonly attribute unsigned int channel: common channel name. Examples "left", "right", "center", "subwoofer"
readonly attribute boolean headphone: true if the speaker is a head phone
readonly attribute unsigned int freqRangeLow: Frequency range, low value, in Hz
readonly attribute unsigned int freqRangeHigh: Frequency range, high value, in Hz

Microphone

readonly attribute boolean stereo: true if the microphone is a stereo mic
readonly attribute unsigned int freqRangeLow: Frequency range, low value, in Hz
readonly attribute unsigned int freqRangeHigh: Frequency range, high value, in Hz

Video

This video specification draws on many references on the Internet on video capabilities. It uses terminology found in the Wikipedia Comparison of Video Codecs

readonly attribute VideoArch archInfo: Video architecture information.
readonly attribute sequence VideoCodec codecs: The list of codecs available on the device.

VideoArch

readonly attribute DOMString impName: Video architecture implementer's name. Example : "Intel"
readonly attribute DOMString todo_hw_info_item: additional TBD hw information here

VideoCodec

readonly attribute DOMString name: Codec name. Example : "Indeo Video" or "libtheora"
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.
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

VideoProfile

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

FrameType

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

RateControl

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

Ambient Light Sensor

Input

The Input API specification is based on the Moblin Platform Awareness Service API.

readonly attribute boolean hasTouchScreen

Indicates whether the device has a touch screen.

readonly attribute boolean supportsHoverEvents

Indicates whether the device supports hover events.

readonly attribute boolean supportsMultiTouch

Indicates whether the device supports multi touch input.

readonly attribute boolean physicalPointingDevicePresent

Indicates whether the device has an physical pointing device attached (e.g. mouse).

readonly attribute boolean physicalKeyboardPresent

Indicates whether the device has a physical keyboard attached.

readonly attribute boolean physicalKeypadPresent

Indicates whether the device has a physical key pad attached (e.g. phone 10 key pad).

readonly attribute boolean softKeyboardVisible

Indicates whether the soft keyboard is visible on the screen.

int watchPhysicalKeyboardChange ( in PhysicalKeyboardChangeCallback successCallback, [Optional] in InputErrorCallback errorCallback)

The watchPhysicalKeyboardChange() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the system to detect the attachment and detachment of physical keyboard devices.
If the attempt fails, and the method was invoked with a non-null errorCallback argument, invoke the errorCallback with a InputChangeError object as an argument.
Invoke the appropriate callback with a new PhysicalKeyboardChange object every time the implementation determines that a physical keyboard has attached or detached.

int watchPhysicalPointerChange ( in PhysicalPointerChangeCallback successCallback, [Optional] in InputErrorCallback errorCallback)

The watchPhysicalPointerChange() function takes one or two arguments. When called, it must immediately return and then asynchronously start a watch process defined as the following set of steps:

Monitor the system to detect the attachment and detachment of physical pointing devices.
If the attempt fails, and the method was invoked with a non-null errorCallback argument, invoke the errorCallback with a InputChangeError object as an argument.
Invoke the appropriate callback with a new PhysicalPointerChange object every time the implementation determines that a physical pointer has attached or detached.

void clearWatch ( in int watchId )

When this method is called, the implementation MUST stop calling the successCallback and errorCallback associated with the watchId.

PhysicalKeyboardChangeCallback

void handleEvent(in PhysicalKeyboardChange physicalKeyboardChange): This function is called whenever the implementation determines that a physical keyboard has attached or detached.

PhysicalPointerChangeCallback

void handleEvent(in PhysicalPointerChange physicalPointerChange): This function is called whenever the implementation determines that a physical pointer has attached or detached.

InputErrorCallback

void handleEvent(in InputChangeError error): This function MUST be called whenever the implementation is unable to monitor physical keyboard and pointer devices on the system.

PhysicalKeyboardChange

readonly attribute boolean keyboardDetached: A physical keyboard was detached.
readonly attribute boolean keyboardAttached: A physical keyboard was attached to the system.
readonly attribute DOMTimeStamp timestamp: Time at which the event occured.

PhysicalPointerChange

readonly attribute boolean pointerDetached: A physical pointer was detached.
readonly attribute boolean pointerAttached: A physical pointer was attached to the system.
readonly attribute DOMTimeStamp timestamp: Time at which the event occured.

InputChangeError

readonly attribute unsigned short UNKNOWN_ERROR: The implementation was unable to monitor the input devices due to an error not covered by the definition of any other error code in this interface.
readonly attribute unsigned short PERMISSION_DENIED: The implementation was unable to monitor the input devices because the application origin does not have permission to use this API.
readonly attribute unsigned short code: Indicates the reason the implementation failed monitor the pointer or keyboard devices.
readonly attribute DOMTimestamp timestamp: The time at which the error occured.

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
A conforming implementation SHOULD provide video architecture
A conforming implementation MAY (TODO)

Ambient Light Sensor

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 detachement of physical pointing devices.
A conforming implementation MAY provide a method for applications to monitor the attachment and detachement of physical keyboard devices.

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 spcial orientations at simultaneously.

Video

Encoding video on the device : app requirments 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 capabilites, and a web service in the cloud that encodes video. This may provide for more efficient compute and network resource utilization.

Video

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

Introduction

Power

PowerLevelCallback

PowerSourceCallback

PowerLevelOptions

PowerLevel

PowerError

CPU

CpuUsageCallback

CpuUsageErrorCallback

CpuUsageOptions

CpuUsage

CpuUsageError

CpuArchitecture

Display

DisplayOrientation

OrientationChangedCallback

ColorDepthChangedCallback

ResolutionChangedCallback

BrightnessChangedCallback

DisplayErrorCallback

DisplayError

Connection

NetworkBearer

Network

WiredNetwork

WirelessNetwork

WifiNetwork

PLMNetwork

CellularNetwork

NetworkTechnology

NetworkStatus

EncryptionMode

ServiceChangeCallback

ServiceChangeErrorCallback

ServiceChangeOptions

NetworkChangeCallback

NetworkChangeErrorCallback

NetworkChangeOptions

ServiceChange

NetworkChange

ServiceChangeError

NetworkChangeError

Thermal

Thermometer

ThermalTarget

TemperatureErrorCallback

TemperatureChangeCallback

TemperatureChangeOptions

TemperatureChange

TemperatureError

Audio

AudioArch

AudioCodec

LineIn

LineOut

Speaker

Microphone

Video

VideoArch

VideoCodec

VideoProfile

FrameType

RateControl

Ambient Light Sensor

Movement

Storage

Input

PhysicalKeyboardChangeCallback

PhysicalPointerChangeCallback

InputErrorCallback

PhysicalKeyboardChange

PhysicalPointerChange

InputChangeError

Requirements

Power

CPU

Display

Connection

Thermal