Bondi logo

The bondi Module - Version 1.01

27 July 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(Object ob)
ErrorCallbackvoid onError(GenericError error)
GenericError
DeviceAPIError
SecurityError
PendingOperationboolean cancel()
bondiPendingOperation requestFeature(SuccessCallback successCallback, ErrorCallback errorCallback, DOMString name)

1. Introduction

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(in Object ob);
        };

Methods

onSuccess

Method invoked when the asynchronous call completes successfully

Signature
void onSuccess(Object ob);
Parameters
  • ob: The object that contains the call result

3.2. 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(GenericError error);
Parameters
  • error: The error that is raised.

3.3. GenericError

Generic error interface. 

        interface GenericError {

                readonly attribute unsigned short code;
        };

Attributes

[readonly] unsigned short code

16-bit error code.

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

This interface inherits from: GenericError

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.5. SecurityError

Security error interface. 

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

The error codes must be in the range 20000-29999

This interface inherits from: GenericError

3.6. 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 one of the callback functions supplied to the operation being cancelled has been called during the call to this method, true otherwise, i.e. the pending operation was cancelled and it was accomplished neither successfully nor errorenously.

3.7. bondi

BONDI root API. 

        [NoInterfaceObject]
        interface bondi {
                PendingOperation requestFeature(in SuccessCallback successCallback,
                                                in ErrorCallback   errorCallback,
                                                in DOMString       name)
                        raises(DeviceAPIError, SecurityError);
        };

Methods

requestFeature

Requests a feature.

Signature
PendingOperation requestFeature(SuccessCallback successCallback, ErrorCallback errorCallback, 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.