Bondi logo

The Bondi bondi 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

Common BONDI functionality.

Table of Contents

Summary of Methods

InterfaceMethod
SuccessCallbackvoid onSuccess()
RequestFeatureSuccessCallbackvoid onSuccess(Object ob)
ErrorCallbackvoid onError(GenericError error)
GenericError
DeviceAPIError
SecurityError
PendingOperationboolean cancel()
BondiPendingOperation requestFeature(RequestFeatureSuccessCallback successCallback, ErrorCallback errorCallback, DOMString name)

1. Introduction

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.

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

These definitions can be used in all other BONDI modules as dependencies.

2. Type Definitions

2.1. StringArray

Array of DOMStrings. 

        typedef sequence<DOMString> StringArray;

2.2. ByteArray

Array of 8-bit unsigned integer values. 

        typedef sequence<octet>     ByteArray;

2.3. ShortArray

Array of 16-bit signed integer values. 

        typedef sequence<short>     ShortArray;

2.4. LongArray

Array of 32-bit signed integer values. 

        typedef sequence<long>      LongArray;

2.5. FloatArray

Array of floating point values. 

        typedef sequence<float>     FloatArray;

2.6. Map

Generic Map object. 

        typedef Object              Map;

3. Interfaces

3.1. SuccessCallback

Generic success callback interface. 

        [Callback=FunctionOnly, NoInterfaceObject] interface SuccessCallback {
                void onSuccess();
        };

Methods

onSuccess

Method invoked when the asynchronous call completes successfully

Signature
void onSuccess();

3.2. RequestFeatureSuccessCallback

Success callback interface for requestFeature invocations 

    [Callback=FunctionOnly, NoInterfaceObject] interface RequestFeatureSuccessCallback {

        void onSuccess(in Object ob);
     };

Methods

onSuccess

Method invoked upon a succesful requestFeature invocation

Signature
void onSuccess(in Object ob);
Parameters
  • ob: Object implementing the JavaScript API associated with the requested Feature.

3.3. ErrorCallback

Generic error callback interface. 

        [Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
                void onError(in GenericError error);
        };

Methods

onError

Method invoked when an error occurs

Signature
void onError(in GenericError error);
Parameters
  • error: The error that is raised.

3.4. GenericError

Generic error interface. 

        interface GenericError {

                readonly attribute unsigned short code;
        };

Attributes

readonly unsigned short code

16-bit error code.

3.5. DeviceAPIError

DeviceApiError error interface. 

        interface DeviceAPIError : GenericError {

                const unsigned short UNKNOWN_ERROR           = 10000;

                const unsigned short INVALID_ARGUMENT_ERROR  = 10001;

                const unsigned short NOT_FOUND_ERROR         = 10002;

                const unsigned short PENDING_OPERATION_ERROR = 10003;

                const unsigned short IO_ERROR                = 10004;

                const unsigned short NOT_SUPPORTED_ERROR     = 10005;
        };

The error codes must be in the range 10000-19999.

Constants

unsigned short UNKNOWN_ERROR

Unknown error.

unsigned short INVALID_ARGUMENT_ERROR

Invalid value was specified as input parameter.

unsigned short NOT_FOUND_ERROR

The searched value or object was not found.

unsigned short PENDING_OPERATION_ERROR

Operation is pending.

unsigned short IO_ERROR

Input/Output error.

unsigned short NOT_SUPPORTED_ERROR

Not supported error.

3.6. SecurityError

Security error interface. 

        interface SecurityError : GenericError {
                const unsigned short PERMISSION_DENIED_ERROR = 20000;
        };

The error codes must be in the range 20000-29999

3.7. PendingOperation

PendingOperation. 

        interface PendingOperation {
                boolean cancel();
        };

Interface that is returned by asynchronous operations in order to provide a cancellation operation.

Methods

cancel

Call to cancel the underlying asynchronous operation.

Signature
boolean cancel();

This call is always successful, i.e. the pending operation i.e. either cancelled or one of the callback is called.

Return value
false if the cancellation did not succeed either because the pending operation finished already or because the cancellation cannot succeed due to technical limitations in the underlying implementation. Consquently the pending operation completes and depending on the success or failure the appropriate callbacks will be called. true if the cancellation did succeed. No callbacks will be called by the cancelled pending operation.

3.8. Bondi

BONDI root API. bondi root property exists in the global object 

        interface Bondi {
                PendingOperation requestFeature(in RequestFeatureSuccessCallback successCallback,
                                                in ErrorCallback   errorCallback,
                                                in DOMString       name)
                        raises(DeviceAPIError, SecurityError);
        };

Methods

requestFeature

Requests a feature.

Signature
PendingOperation requestFeature(in RequestFeatureSuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString name);

This function requests a named feature asynchronously and returns a pending operation object. If it succeeds it calls the successCallback and passes in the object of the requested feature. If it fails it calls the errorCallback passing in a DeviceAPIError which provides an error message and error code indicating the nature of the error.

If the requested feature binds itself to a root namespace ( for example, "bondi.pim.contact") this will happen prior to the successCallback being invoked.

The errorCallback will receive one of the following errors:

Parameters
  • successCallback: the success callback function
  • errorCallback: the error callback function
  • name: the feature name IRI
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • DeviceAPIError:

    UNKNOWN_ERROR if an error occurred and a pending operation object can't be returned.

    NOT_FOUND_ERROR if the requested feature could not be found.

    INVALID_ARGUMENT_ERROR if a malformed argument has been supplied or a required argument has been omitted.

  • SecurityError:

    PERMISSION_DENIED_ERROR if the requested feature is not permitted to load/bind or that access to a required device capability has been denied.

API features
http://bondi.omtp.org/api/bondi.requestfeature