GeographicLocationProvider ObjectThe GeographicLocationProvider Object specification defines an API that provides scripted client functionality for determining the geographic (physical) location of the client.
This document is an early draft designed for submission to the Web API Working Group, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is not currently part of the W3C standards track process, or any similar industry process. Until such time, this document remains the sole copyright of the author, with all rights reserved.
This document may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
GeographicLocationProvider Object
This section is non-normative.
The GeographicLocationProvider object implements an interface exposed by a scripting engine that allows scripts to access information about the geographic location of the client, such as information obtained from a GPS receiver. This information can then be used to provide relevant information to the client, as well as maintain relevancy as the geographic location changes with time. This capability is particularly useful in the context of the "mobile web".
The name of the object is purposefully agnostic from the source of the information as multiple technologies are already commerically deployed, and new technologies can only be expected to emerge in the future.
Due to the obvious privacy concerns surrounding this API, the work already completed by the Geographic Location/Privacy (geopriv) Working Group, part of the Internet Engineering Task Force, was a major influence in the development of this specification.
To provide a consistent "style" of API, much of this API is modelled around the existing XMLHttpRequest object. [XMLHttpRequest]
This section is non-normative.
Some [ECMAScript] examples are listed in the specification. In addition, you can find some below.
Some simple code to retrieve the current latitude and longitude of the client:
function handler()
{
if (this.readyState == 2)
{
alert('Tracking.');
}
}
var provider = new GeographicLocationProvider();
provider.onreadystatechange = handler;
provider.start();Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.
The key words must, must not, should and may in this document are to be interpreted as described in RFC 2119. [RFC2119]
This specification defines the following classes of products:
A user agent must behave as described in this specification in order to be considered conformant.
User agents may optimize any algorithm given in this specification, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms. (The algorithms in this specification are generally written with more concern for clarity than efficiency.)
This specification uses both the terms "conforming user agent(s)" and "user agent(s)" to refer to this product class.
This specification relies on several underlying specifications.
Conforming user agents must support some version of DOM Events and DOM Core, because this specification uses some of the features defined in those specifications. [DOM3Events] [DOM3Core]
It must also support some version of the Window Object because some of the functionality in this specification relies on it. [Window]
Extensions of the API defined by this specification are strongly discouraged. User agents, Working Groups and other interested parties should discuss extensions in a relevant public forum, preferably http://geographiclocationprovider.org/Discussion/.
GeographicLocationProvider ObjectObjects implementing the GeographicLocationProvider interface must also implement the EventTarget interface. [DOM3Events]
Objects implementing the Window interface must provide a GeographicLocationProvider() constructor. [Window]
In ECMAScript this can be used as follows:
var provider = new GeographicLocationProvider();The GeographicLocationProvider interface is defined as follows:
interface GeographicLocationProvider
{
// event handlers
attribute EventListener onreadystatechange;
attribute EventListener onlocationchange;
// states
const unsigned short STOPPED = 0;
const unsigned short RESOLVING = 1;
const unsigned short TRACKING = 2;
const unsigned short UNAVAILABLE = 3;
readonly attribute unsigned short readyState;
// controls
void start();
void stop();
// outputs
readonly Array TODO
};
The GeographicLocationProvider object can be in four states:
STOPPED, RESOLVING,
TRACKING and
UNAVAILABLE. The current state is exposed through the
readyState attribute. Immediately after the state of the object changes, the user agent
must synchronously dispatch a readystatechange event on the object. The
state definitions below define when state transitions take place.
When constructed, the GeographicLocationProvider object
must be in the STOPPED state. The object can return to the STOPPED state from any other state, and
must do so if the stop() method is successfully invoked. This state
is represented by the STOPPED constant, whose value is
0.
The RESOLVING state is the state of the object when the start() method has been successfully
invoked. The object can also enter the RESOLVING state from the TRACKING
state or the UNAVAILABLE state under the conditions described below.
This state is represented by the RESOLVING constant, whose
value is 1.
The TRACKING state is the state of the object when geographic location data has been successfully obtained and can be queried
from the object. The object must only enter the TRACKING state from the
RESOLVING state. If geographic location data is interrupted (for example,
in a GPS context, if the satellite connection was dropped), the object must return to the
RESOLVING state. This state is represented by the
TRACKING constant, whose value is 2.
The UNAVAILABLE state is the state of the object when geographic location data can not be obtained, and is not likely to become
available (for example, if no location-aware devices are connected to the client or the end-user has the feature disabled). The
object must only enter the UNAVAILABLE state from the
RESOLVING state. If geographic location data becomes available (for
example, if a location-aware device was connected), the object may return to the
RESOLVING state. This state is represented by the
UNAVAILABLE constant, whose value is 3.
onreadystatechange of type EventListener
An attribute that takes an EventListener as a value that must be invoked along with any other
appropriate event listeners that are registered on this object when a
readystatechange event is dispatched on it during the bubbling phase. Its
initial value must be null.
onlocationchange of type EventListener
An attribute that takes an EventListener as a value that must be invoked along with any other
appropriate event listeners that are registered on this object when a
locationchange event is dispatched on it during the bubbling phase. Its
initial value must be null.
readyState of type unsigned short, readonlyThe attribute must be the value of the constant corresponding to the object's current state.
start(), methodWhen invoked, the user agent must follow the following steps (unless otherwise indicated):
start() method call,
terminate the overall algorithm and do not process further steps.
(The object is already started.)readystatechange event on the object.start() method call. (Do not terminate the steps in the algorithm though.)readystatechange event on the object.stop(), methodWhen invoked, the user agent must follow the following steps (unless otherwise indicated):
TODO
GeographicLocationProvider ObjectThis section describes the various events that can be dispatched on the object implementing the GeographicLocationProvider interface.
readystatechangereadystatechange event (as indicated above) it must not bubble,
must not be cancelable and must implement the Event interface. Its
namespaceURI attribute must be null. [DOM3Events]
locationchangelocationchange event (as indicated above) it must not bubble,
must not be cancelable and must implement the Event interface. Its
namespaceURI attribute must be null. [DOM3Events]
GeographicLocationProvider ObjectThe GeographicLocationProvider is designed not to throw exceptions from its algorithms.
For circumstances in which the object can not perform the task it is designed to, due to security restrictions, hardware failure, or any other failure, the object transitions to the UNAVAILABLE state. The only state from which this transition can not occur is the STOPPED state, in which the object is not operating anyway.
Avoiding exceptions during the design phase allows for simpler implementations that only need to react to state changes on the object.
TODO
TODO
This section is non-normative.
TODO
This section is non-normative.
Tatham Oddie
This section is non-normative.
The author would like to thank to the following people who have contributed to this specification (ordered by first name):