Bondi logo

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

Location provider.

Table of Contents

Summary of Methods

InterfaceMethod
PositionSuccessCallbackvoid handleEvent(Position position)
PositionErrorCallbackvoid handleEvent(PositionError error)
Geolocationvoid getCurrentPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options)
long watchPosition(PositionSuccessCallback successCallback, PositionErrorCallback errorCallback, PositionOptions options)
void clearWatch(long id)
Coordinates
Position
PositionError
PositionOptions
GeolocationObject

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.

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/spec-source.html.

This implementation is based on a W3C Geolocation Editor's Draft [10 Feb 2010].

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. 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/1.1/geolocation

All the Geolocation features

Includes API features:

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

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 the feature

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

http://bondi.omtp.org/api/1.1/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.3. 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=FunctionOnly, NoInterfaceObject] interface PositionSuccessCallback {
                void handleEvent(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.

Methods

handleEvent

This callback returns the retrieved position object from the location provider.

Signature
void handleEvent(in Position position);
Parameters
  • position: The retrieved position data.

2.2. PositionErrorCallback

The geolocation API specific error callback. 

        [Callback=FunctionOnly, NoInterfaceObject] interface PositionErrorCallback {
                void handleEvent(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.

Methods

handleEvent

The callback handles any kind of errors that may arise during operation.

Signature
void handleEvent(in PositionError error);
Parameters
  • error: The error that is raised during position retrieval.

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

                long watchPosition(in PositionSuccessCallback successCallback,
                                [Optional] in PositionErrorCallback errorCallback,
                                [Optional] in PositionOptions options)
                        raises(SecurityError, DeviceAPIError);

                void clearWatch(in long id)
                        raises (DeviceAPIError);
        };

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

Methods

getCurrentPosition

Receiving asynchronous single shot position information.

Signature
void getCurrentPosition(in PositionSuccessCallback successCallback, in PositionErrorCallback errorCallback, in 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 PositionSuccessCallback is null or if PositionOptions is not null and PositionOptions.timeout < -1 or PositionOptions.maximumAge < 0.

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

 // asynchronous one-shot position call within the given timeframe of 60s
 bondi.geolocation.getCurrentPosition(onPositionSuccess, onPositionError, {timeout:60000});
watchPosition

Obtaining periodic position updates.

Signature
long watchPosition(in PositionSuccessCallback successCallback, in PositionErrorCallback errorCallback, in PositionOptions options);

Requests the Geolocation API to receive the user's current position and to continuously update the position if the position was significantly changed 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/1.1/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);
 }

 // the subscription will call the function onPositionSuccess with
 // the current position until clearWatch is called. The first value
 // should be available within 60 seconds or onPositionError is called.
 // Further position updates will be available at least 60 seconds after
 // the last position update or onPositionError is called each 60 seconds
 // until a new position is available or the watchPosition request is
 // cleared.
 var id = bondi.geolocation.watchPosition(
        onPositionSuccess, onPositionError, {timeout:60000});
clearWatch

Stopping periodic location updates.

Signature
void clearWatch(in long 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.getCurrentPosition(
        function(position) {
                alert("latitude: " + position.coords.latitude);
        }
 );

Attributes

readonly double latitude

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

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

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

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

The altitude of the current position in meters above the ellipsoid.

The value is null if an altitude value cannot be provided.

Code example
 if (position.coords.altitude == 0) {
        alert("sea level");
 }
readonly double 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 double altitudeAccuracy

The altitude accuracy of the position.

The accuracy is given in meters. If altitude accuracy cannot be provided the altitude accuracy value must be null.

Code example
 if (position.coords.altitudeAccuracy == 40) {
        alert("bad altitude accuracy");
 }
readonly double 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 relative to true north (0°). If heading cannot be provided the heading value is null.

Code example
 if (position.coords.heading == 90) {
        alert("heading into east direction");
 }
readonly double 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. The speed value is null if it cannot be provided.

Code example
 if (position.coords.speed == 10) {
        alert("moving with 36km/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 in milliseconds.

Attributes

readonly long timestamp

The time stamp (in milliseconds) indicating when the position was aquired.

Code example
 if(position.timestamp == "1229072400000")
        alert("It is the 12th December 2008 at 9 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 PERMISSION_DENIED = 1;
                
                const unsigned short POSITION_UNAVAILABLE = 2;
                
                const unsigned short TIMEOUT = 3;

                readonly attribute unsigned short code;

                readonly attribute DOMString message;
        };

Constants

unsigned short PERMISSION_DENIED

Permission to acquire a location is not satisfied.

unsigned short POSITION_UNAVAILABLE

A position cannot be determined.

A position cannot be determined, e.g., due to unavailable location providers or internal errors.

unsigned short TIMEOUT

Retrieving a position timed out.

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

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

        [NoInterfaceObject, Callback] interface PositionOptions {
                attribute long timeout;

                attribute long maximumAge;

                attribute boolean enableHighAccuracy;
        };

Position requests can be enriched with options to influence the quality response 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);
 }

 // the subscription should return an accurate position value within the
 //  next 60 seconds, which is not older than 5 minute.
 bondi.geolocation.watchPosition(
        onPositionSuccess, onPositionError,
        {timeout:60000, maximumAge:300000, enableHighAccuracy:true}
 );

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. Thus, a PositionError.code = PositionError.TIMEOUT is never thrown if no timeout is set or the timeout is set to -1.

Code example
 // subscribe for position updates that should return a position
 //  value within the next 10 seconds
 var subscription = bondi.geolocation.watchPosition(
        function() {}, function() {},
        {timeout:10000}
 );
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 maximumAge an 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
 // subscribe for position updates that should return a position
 //  not older then 10 seconds
 var subscription = bondi.geolocation.watchPosition(
        function() {}, function() {},
        {maximumAge:10000}
 );
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
 // subscribe for position updates that should return a very
 //  accurate position without saving any power
 var subscription = bondi.geolocation.watchPosition(
        function() {}, function() {},
        {enableHighAccuracy:true}
 );

2.8. GeolocationObject

Specifies what is instantiated at feature request 

        interface GeolocationObject {
                readonly attribute Geolocation geolocation;
        };
        Bondi implements GeolocationObject;