Bondi logo

The Bondi Geolocation Module: bondi.geolocation - Version 1.0

28 May 2009

Authors

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

Abstract

Location provider.

Table of Contents

Summary of Methods

InterfaceMethod
PositionSuccessCallbackvoid onSuccess(Position position)
PositionErrorCallbackvoid onError(PositionError error)
Geolocationvoid getCurrentPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options)
unsigned integer watchPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options)
void clearWatch(unsigned short id)
Coordinates
Position
PositionError
PositionOptions

1. Introduction

The BONDI Geolocation API is an implementation of the W3C Geolocation API. For more information about the W3C API please visit http://dev.w3.org/geo/api/.

This implementation is based on a W3C Geolocation Editor's Draft [4 May 2009].

The Geolocation API allows for the detection of the user's location by abstracting from a range of location method. For example, an implementation of the Geolocation API can be based on (A)-GPS, Wi-Fi, cell of origin (Cell-ID), IP lookups etc. or on a combination of different location methods.

The Web developer has the choice between one shot requests and watch requests, which allowing for continuous position updates. Both methods have optional parameters like timeout or maximum position age.

1.1. 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 provided is provided.

http://bondi.omtp.org/api/geolocation.position

The API allows the detection of the user's position. Since this may interfere with the user's privacy, requests to get the current position or to watch the user's position are checked for access authority.

Device capabilities: location.position

1.2. Device capabilities

location.position

Detects the device current position

Security parameters:

  • origin: Origin of the data (e.g. network, gps, wifi). The origin is determined by the implementation

2. Interfaces

2.1. PositionSuccessCallback

Success callback for getting position information 

        [Callback] interface PositionSuccessCallback {
                void onSuccess(in Position position);
        };

Success callback that takes a Position object as input argument. It is used in the asynchronous operations to get the current position or watch position changes.

2.2. PositionErrorCallback

The geolocation API specific error callback. 

        [Callback] interface PositionErrorCallback {
                void onError(in PositionError error);
        };

This error callback defines the interface to use for all asynchronous methods of the geolocation API which use error callbacks. The callback is invoked with a PositionError object that describes the occurred error.

2.3. Geolocation

The Geolocation entry point exposed as the Geolocation modules API. 

        interface Geolocation {

                void getCurrentPosition(in PositionSuccessCallback successCallback,
                                        [optional] in PositionErrorCallback errorCallback,
                                        [optional] in PositionOptions options)
                        raises(SecurityError, DeviceAPIError);

                unsigned short watchPosition(in PositionSuccessCallback successCallback,
                                    [optional] in PositionErrorCallback errorCallback,
                                    [optional] in PositionOptions options)
                        raises(SecurityError, DeviceAPIError);

                void clearWatch(in unsigned short id)
                        raises (DeviceAPIError);
        };

This Geolocation class exposes all API functionalities such as receiving or watching the user's position.

Code example
        function errorCB(err) {
                alert("BONDI Geolocation API couldn't be accessed: " + err.message);
        }

        function successCB() {
                // the Geolocation API is successfully loaded
                // and can be used as described in this document
        }

        bondi.requestFeature(successCB, errorCB, "geolocation");

Methods

getCurrentPosition

Receiving asynchronous single shot position information.

Signature
void getCurrentPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options);

Requests the Geolocation API to receive the user's current position with respect to the given (if any) options.

Parameters
  • successCallback: The callback handler for successful location updates.
  • errorCallback: The callback handler for errors during the request.
  • options: All options that specify the requirements for the location request.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if PositionOptions not null and PositionOptions.timeout < -1 or PositionOptions.maximumAge < 0. INVALID_ARGUMENT_ERROR if PositionSuccessCallback is null.
API features
http://bondi.omtp.org/api/geolocation.position
Code example
        // this function will handle each position updates
        function onPositionSuccess(position) {
                alert("longitude: " + position.coords.longitude + " latitude: " + position.coords.latitude);
        }

        // this function will handle each error in position updates
        function onPositionError(error) {
                alert("could not get position: " + error.code);
        }

        // options for the position request (e.g. setting timeout to 10s resp. 10,000ms)
        var options = {};
        options.timeout = 10000;

        try {
                // asynchronous one-shot position call - register our callbacks
                bondi.geolocation.getCurrentPosition(onPositionSuccess, onPositionError, options);
        }
        catch(error) {
                alert("could not request current position: " + error.code);
        }
watchPosition

Obtaining periodic position updates.

Signature
unsigned short watchPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options);

Requests the Geolocation API to receive the user's current position and to continuously update the position until this watch request is deleted by using clearWatch. Optional options can be set.

Parameters
  • successCallback: The callback handler for successful location updates.
  • errorCallback: The callback handler for errors during the request.
  • options: All options that specify the requirements for the location request.
Return value
The identifier for the created subscription. You can delete the subscription with the help of this identifier.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if PositionOptions not null and PositionOptions.timeout < -1 or PositionOptions.maximumAge < 0. INVALID_ARGUMENT_ERROR if PositionSuccessCallback is null.
API features
http://bondi.omtp.org/api/geolocation.position
Code example
        // this function will handle each position update
        function onPositionSuccess(position) {
                alert(position.longitude);
        }

        // this function will handle each error in position update
        function onPositionError(error) {
                alert("could not get position: " + error.code);
        }

        var options = {};
        // the subscription should return a position value within the next 10 seconds
        options.timeout = 10000;

        try {
                // subscribe for position updates
                var id = bondi.geolocation.watchPosition(onPositionSuccess, onPositionError, options);
        }
        catch(error) {
                alert("could not request periodic position updates: " + error.code);
        }
clearWatch

Stopping periodic location updates.

Signature
void clearWatch(unsigned short id);

The API is requested to stop continuously updates of an ongoing subscription.

Parameters
  • id: The identifier for the former created subscription.
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if the given subscription is unknown or the id parameter is null.
Code example
        // subscribe for position updates
        var id = bondi.geolocation.watchPosition(onPositionSuccess, onPositionError, options);
        // do some stuff here
        ...
        try {
                // unsubscribe for position updates
                bondi.geolocation.clearWatch(id);
        }
        catch(error) {
                alert("could not delete subscription: " + error.code);
        }

2.4. Coordinates

The data type to describe a location coordinate. 

        interface Coordinates {

                readonly attribute double latitude;

                readonly attribute double longitude;

                readonly attribute double altitude;

                readonly attribute double accuracy;

                readonly attribute double altitudeAccuracy;

                readonly attribute double heading;

                readonly attribute double speed;
        };

A coordinate contains all data that is needed to uniquely represent the user's position.

Code example
        var position = bondi.geolocation.getLastKnownPosition();
        alert("latitude: " + position.coords.latitude);

Attributes

[readonly] latitude

The latitude of the current position ranging from -90° to +90° (degrees).

Code example
        if(position.coords.latitude == 0) {
                alert("equator");
        }
[readonly] longitude

The longitude of the current position ranging from -180° to +180° (degrees).

Code example
        if(position.coords.longitude == 0) {
                alert("greenwich meridian");
        }
[readonly] altitude

The altitude of the current position ranging from -90° to +90° (degrees).

Code example
        if (position.coords.altitude == 0) {
                alert("sea level");
        }
[readonly] accuracy

The accuracy of the position.

The longitude and latitude accuracy which is given in meters.

Code example
        if (position.coords.accuracy == 2) {
                alert("good accuracy");
        }
[readonly] altitudeAccuracy

The altitude accuracy of the position.

The accuracy is given in meters.

Code example
        if (position.coords.altitudeAccuracy == 40) {
                alert("bad altitude accuracy");
        }
[readonly] heading

The user's or device's heading.

The heading values ranges from 0° to 360° (degrees) and represents the direction in which the user is moving.

Code example
        if (position.coords.heading == 90) {
                alert("heading into east direction");
        }
[readonly] speed

The user's or devices' velocity.

The velocity value is given in meters per second (m/s) and represents how fast the user is moving.

Code example
        if (position.coords.speed == 36) {
                alert("moving with 10km/h");
        }

2.5. Position

The data type, which specifies the position vector of an object. 

        interface Position {

                readonly attribute long timestamp;

                readonly attribute Coordinates coords;
        };

This interface provides all information about the position and associates the coordinates with a timestamp.

Attributes

[readonly] long timestamp

The time stamp indicating when the vector has been created.

Code example
        //if (Date(position.timestamp) == Date("2008/12/12 10:00:00"))
        // this if-statement is not working with real JS date object
        if(position.timestamp == "123404358345") {
                alert("It is the 12th December 2008 at 10 o'clock");
        }
[readonly] Coordinates coords

The coordinates indicating where the user is located.

Code example
 if (position.coords)
        alert("longitude: " + location.coords.longitude);

2.6. PositionError

Generic error interface. 

        interface PositionError {
                const unsigned short UNKNOWN_ERROR = 0;
                const unsigned short POSITION_UNAVAILABLE_ERROR = 2;
                const unsigned short TIMEOUT_ERROR = 3;

                readonly attribute unsigned short code;

                readonly attribute DOMString message;
        };

Attributes

[readonly] unsigned short code

The error code of this error event.

Code example
        // the onEvent method of the ErrorCallback
        function onEvent(error) {
                // react if the error was raise because of a timeout
                if(error.code == PositionError.TIMEOUT_ERROR)
                        alert("cannot provide location in the given time");
        }
[readonly] DOMString message

A description of the error.

Code example
        // the onEvent method of the ErrorCallback
 function onEvent(error) {
        // print out the error message
        alert("Error " + error.code + ": " + error.message );
 }

2.7. PositionOptions

Definition of options that can be used for location requests. 

        interface PositionOptions {

                attribute long timeout;

                attribute long maximumAge;

                attribute boolean enableHighAccuracy;
        };

Position requests can be enriched with options to influence the quality reponse time of the location provider.

Code example
        // this function will handle each position update
        function onPositionSuccess(position) {
                alert(position.longitude);
        }

        // this function will handle each error in position update
        function onPositionError(error) {
                alert("could not get position: " + error.code);
        }

        var options = {};
        // the subscription should return a position value within the next 10 seconds
        options.timeout = 30000;

        bondi.geolocation.watchPosition(successCallback, errorCallback, options);

Attributes

long timeout

Specification of a timeout value in milliseconds.

After the timeout interval has elapsed an error is thrown in order to inform all requesting/subscribed applications about the unavailability of position data. The default value is -1 which is interpreted as no timeout. i.e., a PositionError.code = PositionError.TIMEOUT is never thrown if no timeout is set or the timeout is set to -1.

Code example
        var successCallback = {};
        var errorCallback = {};
        var options = {};
        // the subscription should return a position value within the next 10 seconds
        options.timeout = 10000;

        // subscribe for position updates
        var subscription = bondi.geolocation.watchPosition(successCallback, errorCallback, options);
long maximumAge

Specification of the maximum age of position data.

This value is given in milliseconds. If the time since the last position data was recorded exceeds the maximumAgean error is thrown to inform all involved applications. The default value is 0 which means that no cached data is used and a new location must be acquired.

Code example
        var successCallback = {};
        var errorCallback = {};
        var options = {};
        // the subscription should return a position not older then 10 seconds
        options.maximumAge = 10000;

        // subscribe for position updates
        var subscription = bondi.geolocation.watchPosition(successCallback, errorCallback, options);
boolean enableHighAccuracy

The demand for high/best-effort accuracy.

For high accuracy the accuracy parameter must be set to true.

When set indicates that a high accuracy for positioning is required even if it is at the expense of higher power consumption or slower response time. The default is false.

Code example
        var successCallback = {};
        var errorCallback = {};
        var options = {};
        // the subscription should return a very accurate position without saving any power
        options.enableHighAccuracy = true;

        // subscribe for position updates
        var subscription = bondi.geolocation.watchPosition(successCallback, errorCallback, options);