Bondi logo

The Bondi devicestatus Module - Version 1.1

26 October 2009

Authors

© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

Provides access to the device status from the web context

Table of Contents

Summary of Methods

InterfaceMethod
PropertyChangeSuccessCallbackvoid onPropertyChange(PropertyRef property, Object newValue)
DeviceStatusError
DeviceStatusManagerStringArray listVocabularies()
void setDefaultVocabulary(DOMString vocabulary)
StringArray listAspects()
StringArray getComponents(AspectName aspect)
StringArray listProperties(AspectName aspect)
Object getPropertyValue(PropertyRef prop)
void setPropertyValue(PropertyRef pref, Object value)
unsigned long watchPropertyChange(PropertyRef pref, PropertyChangeSuccessCallback listener, Map options)
void clearPropertyChange(unsigned long watchHandler)
AspectName
PropertyRef
DeviceStatusManagerObject

1. Introduction

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.1. Feature set

This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.

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

All the DeviceStatus features

Includes API features:

  • http://bondi.omtp.org/api/devicestatus.get
  • http://bondi.omtp.org/api/devicestatus.set
  • http://bondi.omtp.org/api/devicestatus.list

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 any of the features

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

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

Call to getPropertyValue or addEventListener in DeviceStatusManager

Device capabilities:

  • devicestatus.get
http://bondi.omtp.org/api/devicestatus.set

Call to setPropertyValue in DeviceStatusManager

Device capabilities:

  • devicestatus.set
http://bondi.omtp.org/api/devicestatus.list

Call to listVocabularies, listAspects, listProperties or getComponents in DeviceStatusManager

Device capabilities:

  • devicestatus.list

1.3. Device capabilities

devicestatus.get

Get (or subscribe to) device status property value

Security parameters:

  • vocabulary: Vocabulary IRI
  • component: Component Identifier
  • aspect: Local Aspect Name
  • property: Local Property Name
devicestatus.set

Set device status property value

Security parameters:

  • vocabulary: Vocabulary IRI
  • component: Component Identifier
  • aspect: Local Aspect Name
  • property: Local Property Name
devicestatus.list

List available elements in the vocabulary

Security parameters:

  • level: One of (vocabulary, aspect, component, property)

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

Device Status specific errors. 

        interface DeviceStatusError : GenericError {

                const unsigned short READ_ONLY_PROPERTY_ERROR             = 1;
        };

Constants

unsigned short READ_ONLY_PROPERTY_ERROR

Property is read only

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

                void setPropertyValue(in PropertyRef pref, in Object value)
                        raises(SecurityError, DeviceAPIError, DeviceStatusError);

                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
API features
http://bondi.omtp.org/api/devicestatus.list
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
API features
http://bondi.omtp.org/api/devicestatus.list
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.

API features
http://bondi.omtp.org/api/devicestatus.list
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.

API features
http://bondi.omtp.org/api/devicestatus.list
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.

API features
http://bondi.omtp.org/api/devicestatus.get
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"});
setPropertyValue

Sets the value of a property

Signature
void setPropertyValue(in PropertyRef pref, in Object value);

This method changes the value of a property to that given by the value parameter

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.
- 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.
- If the property can not be written a DeviceStatusError with code READ_ONLY_PROPERTY_ERROR will be raised

Parameters
  • pref: The property ref
  • value: The value
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.

  • DeviceStatusError:

    READ_ONLY_PROPERTY_ERROR if the supplied PropertyRef is found, but it is read-only.

API features
http://bondi.omtp.org/api/devicestatus.set
Code example
        bondi.devicestatus.setPropertyValue({property:"orientation", aspect:"Display"}, 0);
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 notifification, 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.

API features
http://bondi.omtp.org/api/devicestatus.get
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

API features
http://bondi.omtp.org/api/devicestatus.get
Code example
        bondi.devicestatus.clearPropertyChange(orientationChangeHandler);

2.4. 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.5. 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.6. DeviceStatusManagerObject

Specifies what is instantiated at feature request 

        interface DeviceStatusManagerObject {
                readonly attribute DeviceStatusManager deviceStatusManager; 
        };
        Bondi implements DeviceStatusManagerObject;