The Bondi devicestatus Module - Version 1.1

February 2010

Authors

Mario Arias <marioarias2@gmail.com>
Jose Manuel Cantera <jmcf@tid.es>
Daniel Coloma <dcoloma@tid.es>
Fernando Rodriguez <frsela@tid.es>
Rubén Soto <rsd@tid.es>

Abstract

Provides access to the device status from the web context

1. Introduction
- 1.2. Features
- 1.3. Device Capabilities
2. Interfaces
- 2.1. PropertyChangeSuccessCallback
- 2.2. DeviceStatusManager
- 2.3. AspectName
- 2.4. PropertyRef
- 2.5. DeviceStatusManagerObject

Summary of Methods

Interface	Method
PropertyChangeSuccessCallback	void onPropertyChange(PropertyRef property, Object newValue)
DeviceStatusManager	StringArray listVocabularies() void setDefaultVocabulary(DOMString vocabulary) StringArray listAspects() StringArray getComponents(AspectName aspect) StringArray listProperties(AspectName aspect) Object getPropertyValue(PropertyRef prop) unsigned long watchPropertyChange(PropertyRef pref, PropertyChangeSuccessCallback listener, Map options) void clearPropertyChange(unsigned long watchHandler)
AspectName
PropertyRef
DeviceStatusManagerObject

1. Introduction

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

The status information is organized in a tree of properties grouped by category. The interface provides methods to browse the tree, to get/set the value of a selected property and to set up asynchronous notifications of changes in certain values.

This interface defines the access to the properties of the DeviceStatus but does not specify which aspects or properties are available. To browse a comprehensive list of properties, please refer to the BONDI Property Classification document.

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When the feature

http://bondi.omtp.org/api/1.1/devicestatus

is successfully requested, the interface DeviceStatusManager is instantiated, and the resulting object appears in the global namespace as Bondi.devicestatus.

http://bondi.omtp.org/api/1.1/devicestatus

Call to getPropertyValue or addEventListener in DeviceStatusManager

Device capabilities:

devicestatus

1.3. Device capabilities

devicestatus: Get (or subscribe to get) device status property value

2. Interfaces

2.1. `PropertyChangeSuccessCallback`

Device Status Listener success callback.

        [Callback=FunctionOnly, NoInterfaceObject] interface PropertyChangeSuccessCallback {
                void onPropertyChange(in PropertyRef property, in Object newValue);
        };

Success callback for notifying changes to a property. When the callback is invoked its input parameters are the PropertyRef of the property being watched and its new value.

Methods

onPropertyChange

Method invoked to notify about property changes

Signature

void onPropertyChange(in PropertyRef property, in Object newValue);

Parameters

property: The reference to the property that has changed
newValue: The value that contains the property

2.2. `DeviceStatusManager`

Simple Context API for querying/modifying the status of the device (BONDI Terminal Status Interfaces Requirements, Section 9)

         interface DeviceStatusManager {

                StringArray listVocabularies();

                void setDefaultVocabulary(in DOMString vocabulary)
                    raises(DeviceAPIError);

                StringArray listAspects();

                StringArray getComponents(in AspectName aspect)
                        raises(DeviceAPIError);

                StringArray listProperties(in AspectName aspect)
                        raises(DeviceAPIError);

                Object getPropertyValue(in PropertyRef prop)
                        raises(SecurityError, DeviceAPIError);

                unsigned long watchPropertyChange(in PropertyRef pref,
                                         in PropertyChangeSuccessCallback listener,
                                         in Map options)
                        raises(SecurityError, DeviceAPIError);

                void clearPropertyChange(in unsigned long watchHandler)
                        raises(DeviceAPIError);
        };

This module offers the functionality to get information about the device status. The status information is structured in:

- "Vocabularies": (similar to namespaces) BONDI has specified a vocabulary available at BONDI Vocabulary

- "Aspects": A vocabulary is composed of different aspects that gather information related to a unique aspect of the device (e.g. 'WebBrowser', 'GraphicDisplay', 'Memory').

- "Components": An aspect may comprise different components that are intended to describe different instances of the same aspect (e.g. 'Memory' aspect may have three different components 'physical', 'virtual', 'storage'). There are two special component identifiers:
* _default: which denotes the default component of an aspect
* _active: which denotes the Active component of an aspect

- "Properties": Aspects are composed of properties which provide information about a particular property of the component, for instance for every 'Memory' component the properties 'total', 'available', 'removable' are supported.

When trying to resolve a property, the only mandatory parameter is the property name. If no other data is specified the implementation will look in the default vocabulary for the default aspect/component pair including a property with the given name.

Code example

        // Get the batteryLevel property of the Battery aspect.
        var batteryLevel = bondi.devicestatus.getPropertyValue({property:"batteryLevel", aspect:"Battery", component:"_default"});
        alert("The current battery level is: " + batteryLevel);

Methods

listVocabularies

Lists the vocabularies available

Signature

StringArray listVocabularies();

Every vocabulary returned is identified by an IRI. At the very least BONDI vocabulary will always be available. Other vocabularies may also be implemented.

Return value

An array of IRIs that identify the vocabularies available

Code example

        var vocabularies = bondi.devicestatus.listVocabularies();

setDefaultVocabulary

Sets the default vocabulary to be used when a vocabulary is not specified.

Signature

void setDefaultVocabulary(in DOMString vocabulary);

The selected vocabulary specified in the input parameter MUST be one of the returned by the listVocabularies() method. In case the vocabulary is not found, a DeviceAPIError with NOT_FOUND_ERROR code will be raised. By default, BONDI vocabulary is selected.

Parameters

vocabulary: An IRI which identifies the vocabulary

Exceptions

DeviceAPIError:

INVALID_ARGUMENT_ERROR if no vocabulary is supplied i.e. null, undefined or empty string.

NOT_FOUND_ERROR if the supplied vocabulary does not belong to the list of implemented vocabularies.

Code example

        bondi.devicestatus.setDefaultVocabulary("http://bondi.omtp.org");

listAspects

Lists all the aspects for a specific vocabulary.

Signature

StringArray listAspects();

An aspect is a category of properties, like Battery, Display or NetworkConnection. This method returns a list of all the aspects supported by a specific vocabulary.

If no explicit vocabulary is specified, the default vocabulary is used.

Return value

The list of aspects

Code example

        var aspects = bondi.devicestatus.listAspects();

getComponents

Returns the name of all the components that are instances of the specified aspect.

Signature

StringArray getComponents(in AspectName aspect);

This method provides information on all the different components that compose an aspect. An aspect is determined by the vocabulary IRI and the aspect name.

If no vocabulary is specified, the default vocabulary will be used.

If the vocabulary or the aspect do not have a valid value, the method will return a DeviceAPIError with code INVALID_ARGUMENT_ERROR

If the aspect is valid, but the implementation has not implemented that aspect, the method will raise a DeviceAPIError with code NOT_FOUND_ERROR

If the vocabulary exists and the aspect is valid, it will return all the different components part of the aspects.

Parameters

aspect: The Aspect

Return value

The list of Component names

Exceptions

DeviceAPIError:

NOT_FOUND_ERROR if the supplied AspectName is valid, but the implementation has not implemented that aspect.

INVALID_ARGUMENT_ERROR if the supplied AspectName.aspect does not have a valid value.

Code example

        var cameras = bondi.devicestatus.getComponents({aspect:'Camera'});

listProperties

Returns the names of all the properties in the specified aspect.

Signature

StringArray listProperties(in AspectName aspect);

An aspect is determined by the vocabulary IRI and the aspect name.

If no vocabulary is specified the default vocabulary will be used.

If the vocabulary or the aspect do not have a valid value the method will return a DeviceAPIError with code INVALID_ARGUMENT_ERROR

If the aspect is valid but the implementation has not implemented that aspect the method will raise a DeviceAPIError with code NOT_FOUND_ERROR

If the vocabulary exists and the aspect is valid it will return all the different properties part of the aspects.

Parameters

aspect: The Aspect

Return value

The list of local Property names

Exceptions

DeviceAPIError:

NOT_FOUND_ERROR if the supplied AspectName is valid, but the implementation has not implemented that aspect.

INVALID_ARGUMENT_ERROR if the supplied AspectName.aspect does not have a valid value.

Code example

        var props = bondi.devicestatus.listProperties({aspect:'Camera'});

getPropertyValue

Returns the value of a specific property referenced by a PropertyRef.

Signature

Object getPropertyValue(in PropertyRef prop);

This method returns the value of a property in a vocabulary.

The property name is mandatory; the vocabulary, aspect and components are optional. The implementation will use the following rules if optional elements are not specified:
- If no vocabulary is specified, the default vocabulary will be used.
- If the aspect is not specified, the first aspect with a property matching the property name will be used.
- If the component is not specified, the primary component of the given aspect will be used.
- If an invalid propertyName is specified a DeviceAPIError with code INVALID_ARGUMENT_ERROR will be raised.
- If the propertyName is valid but the implementation has not implemented that property a DeviceAPIError with code NOT_FOUND_ERROR will be raised.

Parameters

prop: The propertyRef

Return value

The value of the Property (represented by the appropriate JS type) or 'undefined' if the property value is not currently available.

Exceptions

SecurityError:

PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError:

NOT_FOUND_ERROR if the supplied PropertyRef is valid, but the implementation has not implemented that property.

INVALID_ARGUMENT_ERROR if the supplied PropertyRef does not have a valid propertyName value.

Code example

        var level = bondi.devicestatus.getPropertyValue({property:"batteryLevel", aspect:"Battery", component:"_default"});

        // The above call is equivalent to:
        var level = bondi.devicestatus.getPropertyValue({property:"batteryLevel", aspect:"Battery"});

        // or 
        var level = bondi.devicestatus.getPropertyValue({property:"batteryLevel"});

watchPropertyChange

Registers for property change notifications.

Signature

unsigned long watchPropertyChange(in PropertyRef pref, in PropertyChangeSuccessCallback listener, in Map options);

The property name in the pref attribute is mandatory; the vocabulary, aspect and component are optional. The implementation will use the following rules if optional elements are not specified:
- If no vocabulary is specified the default vocabulary will be used.
- If the aspect is not specified the first aspect with a property matching the property name will be used.
- If the component is not specified the primary component of the given aspect will be used.

The callback argument is mandatory. Whenever the watched property value changes the system will call the supplied callback passing the full PropertyRef of the modified property and the property's new value.

The options argument is optional, and is used to specify the granularity of the notifications. If any option is invalid it will be ignored. The permitted options are:
- "minTimeout": Minimum time between notifications, expressed in milliseconds. Default value 0.
- "maxTimeout": Maximum time between notification, expressed in milliseconds. The callback will be called after the specified time even if the property has not changed in the meantime. maxTimeout must always be greater than minTimeout. Default value: infinite.
- "callCallbackOnRegister": Call the callback just after the callback was registered. Simplifies the task of inlining the implementation of the callback and initializing the application. Default value: false.
- "minChangePercent": Sets the minimum change percent of the value, when the type is numeric. For example if the last value was 100, and the specified minChangePercent is 20%, Then the value must go under 80 or over 120 to get notified. Default value: 0.

If an invalid propertyName is specified, a DeviceAPIError with code INVALID_ARGUMENT_ERROR will be raised.

If the propertyName is valid, but the implementation has not implemented that property, a DeviceAPIError with code NOT_FOUND_ERROR will be raised.

Parameters

pref: the property reference to the property to be notified of changes.
listener: callback to be invoked whenever the event is raised.
options: The set of options which will specify the granularity of notifications.

Return value

watchHandler Handler to be used to unregister from notifications using DeviceStatusManager::clearPropertyChange() call.

Exceptions

SecurityError:

PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError:

NOT_FOUND_ERROR if the supplied PropertyRef is valid, but the implementation has not implemented that property.

INVALID_ARGUMENT_ERROR if the supplied PropertyRef does not have a valid propertyName value.

Code example

        var orientationChangeHandler = bondi.devicestatus.watchPropertyChange({aspect:"display", property:"orientation"}, 
                {
                        onPropertyChange:function(ref, value) {
                                alert("Property changed: "+ref.property+" "+ref.component+" "+ref.aspect+" "+ref.vocabulary);
                                alert("New value: "+value);
                        }
                }, {
                        minTimeout:1000,
                        callCallbackOnRegister:true
                }
        );

clearPropertyChange

Unregister notifications from a property change.

Signature

void clearPropertyChange(in unsigned long watchHandler);

If the watchHandler identifier does not exist, a DeviceAPIError with code INVALID_ARGUMENT_ERROR will be raised

Parameters

watchHandler: returned by DeviceStatusManager::watchPropertyChange()

Exceptions

DeviceAPIError:

INVALID_ARGUMENT_ERROR if the supplied watchHandler does not exist

Code example

        bondi.devicestatus.clearPropertyChange(orientationChangeHandler);

2.3. `AspectName`

Class to unequivocally refer to an aspect by its name and vocabulary (namespace)

        interface AspectName {

                 attribute DOMString aspect;

                 attribute DOMString vocabulary;
        };

If no vocabulary is specified the default vocabulary will be used.

Attributes

DOMString aspect

Local Aspect Name

Code example

   ref.aspect = "battery";

DOMString vocabulary

Vocabulary IRI (the namespace)

Code example

 
   ref.vocabulary = BONDI_VOC;

2.4. `PropertyRef`

Full reference to a property, specified by the property name, the component name, the aspect name and the vocabulary namespace. It is used to refer to a single property inside the vocabulary. The "property" attribute is mandatory and the remainder optional.

         interface PropertyRef {

                attribute DOMString vocabulary;

                attribute DOMString component;

                attribute DOMString aspect;

                attribute DOMString property;
        };

Code example

        var dpiXProperty = {property:"dpiX"};
        var batteryLevelProperty = {vocabulary:BONDI_VOC, aspect:"battery", component:"default", property:"batteryLevel" };

Attributes

DOMString vocabulary: Vocabulary IRI (optional)
DOMString component: Component Identifier (optional)
DOMString aspect: Local Aspect Name (optional)
DOMString property: Local Property Name (mandatory)

2.5. `DeviceStatusManagerObject`

Specifies what is instantiated at feature request

        interface DeviceStatusManagerObject {
                readonly attribute DeviceStatusManager devicestatus; 
        };

        Bondi implements DeviceStatusManagerObject;

The Bondi devicestatus Module - Version 1.1

February 2010

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

1.2. Features

1.3. Device capabilities

2. Interfaces

2.1. PropertyChangeSuccessCallback

Methods

Signature

Parameters

2.2. DeviceStatusManager

Code example

Methods

Signature

Return value

Code example

Signature

Parameters

Exceptions

Code example

Signature

Return value

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

2.3. AspectName

Attributes

Code example

Code example

2.4. PropertyRef

Code example

Attributes

2.5. DeviceStatusManagerObject

2.1. `PropertyChangeSuccessCallback`

2.2. `DeviceStatusManager`

2.3. `AspectName`

2.4. `PropertyRef`

2.5. `DeviceStatusManagerObject`