Accessing +device location information

The Location +Service API allows widgets to retrieve information about +the physical location of a device and to perform calculations based on location +information. You can use the Location Service to create widgets that +provide location-based services (LBS). For example, you can create widgets that:

Provide directions to a destination, for example the nearest +restaurant
Monitor the locations of snow-plowing vehicles
Calculate distances between geographical locations
+

The Location Service relies on the GPS capabilities of the device to +provide location information. If the device does not include or is not connected +to a positioning system, the service cannot provide such information.

Accessing the API and supported methods

To create a service +object for the Location Service API, use Service.Location to +identify the service provider and ILocation to identify +the supported interface:

+ +

var so = device.getServiceObject("Service.Location", "ILocation");

The ILocation interface provides the following +methods:

GetLocation()
+ +
Use the GetLocation() method to retrieve the current +location of the device.
+ +
Trace()
+ +
Use the Trace() method to retrieve periodic updates +about the current location of the device.
+ +
Calculate()
+ +
Use the Calculate() method to perform mathematical +calculations based on a source location and a target location.
+ +
CancelNotification()
+ +
Use the CancelNotification() method to cancel an +ongoing asynchronous call. This method is valid for any asynchronous call +made through the Location Service API.
+ +

Using the service in a widget

To access location information using the Location Service API:

Create a service +object for the API using device.getServiceObject().
+
Define the +tasks you want to perform and choose the correct methods for them.
+
Optionally, +define how you want the results filtered.
Define methods +for processing the results.
Retrieve the +location information using the methods defined in step 2. Use asynchronous +methods together with callback().
+
Process the +results with the methods defined in step 4.

For the complete source of a sample widget that demonstrates how to +use this service, see the full example.