This component provides a JavaScript API that abstracts away device specific APIs, allowing page authors to easily utilize the device's GPS capabilities. The cf2:Geolocator component uses this API to provide a simple mechanism for obtaining the location information within a Client Framework 2 application.
The following API is based on the W3C Geolocation API Candidate Recommendation.
n/a
The V$.geo object provides the following methods:
Initiates an asynchronous attempt to obtain the current location of the device. Callback functions will be called at most once.
| Parameter | Description | Type |
|---|---|---|
| successCallback | A callback function to be called when the position is acquired successfully. | PositionCallbackFunction |
| errorCallback | A callback function to be called when the position cannot be acquired. | PositionErrorFunction |
| options | An optional set of position options. | PositionOptions |
Triggers the process of watching the position of the device. The method returns the identifier of a watch operation that has just been started. The position callback function will be asynchronously called to acquire a more accurate position, or a new position when the location of the device changes.
| Parameter | Description | Type |
|---|---|---|
| successCallback | A callback function to be called when the position is acquired successfully. | PositionCallbackFunction |
| errorCallback | A callback function to be called when the position cannot be acquired. | PositionErrorFunction |
| options | An optional set of position options. | PositionOptions |
Stops the selected watch process.
| Parameter | Description | Type |
|---|---|---|
| watchId | The identifier of the watch process to stop. | long |
The position callback function is called with a single parameter of type Position. The following table lists its properties.
Position Properties
| Name | Description | Type |
|---|---|---|
| coords | A set of coordinates. Refer to Coordinates for a list of the available properties. | coordinates |
| timestamp | Represents the time when the Position object was acquired. | Date |
Coordinates
| Name | Description | Type |
|---|---|---|
| latitude | The latitude coordinate; specified in decimal degrees. | double |
| longitude | The longitude coordinate; specified in decimal degrees. | double |
| altitude | The vertical height specified in meters compared to the ellipsoid defined by the World Geodetic System specification. If the information cannot be provided, the value of this property is null. | double |
| accuracy | The accuracy level, in meters, of the latitude and longitude coordinates. The value of the property is a non-negative real number. | double |
| altitudeAccuracy | The accuracy level of the altitude, specified in meters. The value of the property is a non-negative real number. If the information cannot be provided, the value of this property is null. | double |
| heading | The direction of travel of the device; specified in degrees, where 0° ≤ heading < 360°, counting clockwise relative to the true north. If the device is stationary, i.e. the value of the speed property is '0', then the value of this property is NaN. If the information cannot be provided, the value of this property is null. | double |
| speed | The current ground speed of the device, in meters per second. The value of the property is a non-negative real number. If the information cannot be provided, the value of this property is null. | double |
The error function is called with a single parameter of type PositionError. The following table lists its properties.
| Name | Description | Type |
|---|---|---|
| code | Error code. The values have the following meanings: 0 - unknown error, 1 - permission denied, 2 - position unavailable, 3 - timeout. | short |
| message | A message describing the details of the problem. | string |
The Position Options object is a plain Map and can consist of the following optional parameters.
| Name | Description | Type |
|---|---|---|
| enableHighAccuracy | If set to 'true', then the device will try to provide the best accuracy possible. Please note that it may result in a slower response time and increased power consumption. The default value is 'false'. | boolean |
| timeout | Determines how long a request will wait for a new location information. The value of the option must be greater than or equal to '0'. A value of '0' means that the request will return a cached location if it does not exceed the maximum age; otherwise it will fail immediately with a timeout error. The default value is '20000', i.e. 20 seconds. | long |
| maximumAge | Indicates that the application is willing to accept a cached position whose age is no greater than the specified time in milliseconds. The value of the option must be greater than or equal to '0'. A value of '0' will cause the request to attempt to obtain the current location. A value of 'Infinity' will allow it to use a cached location if available. The default value is '600000', i.e. 600 seconds. | long |