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:

  1. Create a service object for the API using device.getServiceObject().

  2. Define the tasks you want to perform and choose the correct methods for them.

  3. Optionally, define how you want the results filtered.

  4. Define methods for processing the results.

  5. Retrieve the location information using the methods defined in step 2. Use asynchronous methods together with callback().

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

© Nokia 2008.