Bondi logo

The Bondi bondi Module - Version 1.1

February 2010

Authors

© 2009-2010 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)
FeatureCallbackvoid onFeatureLoaded(FeatureArray loadedFeatures)
GenericError
DeviceAPIError
SecurityError
PendingOperationboolean cancel()
void wait()
GenericFilter
BondiPendingOperation requestFeature(RequestFeatureSuccessCallback successCallback, ErrorCallback errorCallback, DOMString name)
FeatureArray getFeatures()
long watchFeatures(FeatureCallback callback)
void clearWatch(long watch)

1. Introduction

Copyright 2010 OMTP Ltd.

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.

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

Array of Feature IRIs. 

        typedef sequence<DOMString> FeatureArray;

2.3. ByteArray

Array of 8-bit unsigned integer values. 

        typedef sequence<octet>     ByteArray;

2.4. ShortArray

Array of 16-bit signed integer values. 

        typedef sequence<short>     ShortArray;

2.5. LongArray

Array of 32-bit signed integer values. 

        typedef sequence<long>      LongArray;

2.6. FloatArray

Array of floating point values. 

        typedef sequence<float>     FloatArray;

2.7. 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 successful 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. FeatureCallback

Feature callback interface. 

        [Callback=FunctionOnly, NoInterfaceObject] interface FeatureCallback {
                void onFeatureLoaded(in FeatureArray loadedFeatures);
        };

Methods

onFeatureLoaded

Called when features become available.

Signature
void onFeatureLoaded(in FeatureArray loadedFeatures);
Parameters
  • loadedFeatures: Features that have been successfully loaded

3.5. GenericError

Generic error interface. 

        interface GenericError {
                readonly attribute unsigned short code;
        };

Attributes

readonly unsigned short code

16-bit error code.

3.6. 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.7. 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.8. PendingOperation

PendingOperation. 

        interface PendingOperation {
                boolean cancel();

                void wait();
        };

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. Consequently the pending operation completes and depending on the success or failure the appropriate callbacks will be called after this method returns. true if the cancellation did succeed. No callbacks will be called by the cancelled pending operation. A call to the PendingOperation.cancel() on the instance of the PendingOperation interface that waits for completion of the asynchronous operation initiated by the call to PendingOperation.wait() results in PendingOperation.cancel() returning false, i.e. the cancellation shall not succeed.
wait

Call to wait until the underlying asynchronous operation completes.

Signature
void wait();

This method is intended for use in cases where the BONDI asynchronous method should accomplish in synchronous-like manner. This is specifically important in the realization of the shim-layers that convert between various (a)synchronicity models. This call blocks the current execution thread until the PendingOperation completes. Depending on the success or failure of the PendingOperation result, the appropriate callbacks will be called before this method returns. A call to the PendingOperation.wait() on any instance of the PendingOperation interface, from within one of the callbacks results in no operation. This is to prevent deadlocks by improper use of the wait() method. A call to the PendingOperation.cancel() on any instance of the PendingOperation interface from within one of the callbacks results in PendingOperation.cancel() returning falsei.e. the cancellation shall not succeed.

Code example
 var loadingsuccessful = 0;
 
 function successCB()
 {
                alert("SUCCESS");
                loadingsuccessful = 1;
 }
 
 function errorCB()
 {
                alert("ERROR");
                loadingsuccessful = 0;
 }
 
 function loadFeatureSynchronously()
 {
                var asyncop = bondi.requestFeature(successCB, errorCB, "http://bondi.omtp.org/api/messaging");
                asyncop.wait(); // waiting for messaging API to be loaded
                alert("Feature loading accomplished");
      return loadingsuccessful; // if 1, the messaging API was loaded synchronously and successfully
 }
 
 // The bondi.requestFeature() method is asynchronous by design.
 // bondi.requestFeature() start dummy asynchronous operation.
 // The call to loadFeatureSynchronously() results in SUCCESS or ERROR prompt prior to Feature loading accomplished prompt.

3.9. GenericFilter

Generic filter interface. All filter object must inherit from this interface. 

        interface GenericFilter {

        };

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

                FeatureArray getFeatures();

                long watchFeatures(in FeatureCallback callback);

                void clearWatch(in long watch);
        };

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.

Errors that may be returned in the ErrorCallback:

  • 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.
  • DeviceAPIError INVALID_ARGUMENT_ERROR if a malformed argument has been supplied or a required argument has been omitted.
  • DeviceAPIError NOT_FOUND_ERROR if the requested feature could not be found.
  • DeviceAPIError UNKNOWN_ERROR if an error occurred and a pending operation object can't be returned.
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.
API features
http://bondi.omtp.org/api/bondi.requestfeature
Code example
   bondi.requestFeature(successCB, errorCB, "http://bondi.omtp.org/api/messaging");
getFeatures

Returns all available features.

Signature
FeatureArray getFeatures();
Return value
array of available features.
watchFeatures

Registers a listener to be notified of changes in the availability of features.

Signature
long watchFeatures(in FeatureCallback callback);
Parameters
  • callback: the listener.
Return value
Watch id of the listener.
clearWatch

Unregisters a previously registered listener.

Signature
void clearWatch(in long watch);
Parameters
  • watch: the watch id.