Location Acquisition API overview

This document describes the Location Acquisition API. Client applications use the API to obtain the location of the mobile device and to discover the type and status of the available positioning modules.

The Location Acquisition API defines the client application view of the LBS location server. The API is a standard Symbian OS client-server implementation. Applications use the API to:

• Obtain the location of the mobile device

  The Location Acquisition API is designed so that client applications can always make the same API calls to obtain the device location irrespective of the underlying positioning technologies used by the location server.

• Discover the type and status of available positioning technologies

  The API allows applications to discover the available positioning technology modules and to receive notification of changes in their status. Applications can also make a choice of the specific positioning technology module to use to get the device location.

Location server

The Symbian OS server used by client applications to get location information. The location server is part of the location framework. The location server can use multiple positioning technology modules to obtain location information. Location information can be obtained from the network and from A-GPS hardware.

Location framework

The part of the LBS subsystem that handles requests for location from client applications and from the network. Components within the location framework interact with positioning technology modules to get location information.

Positioning technology module

A software component that handles requests for location information and interfaces with the underlying positioning technology hardware or the network.

Figure 1 illustrates the client interface classes of the Location Acquisition API including the data classes that hold basic location information. To use the Location Acquisition API, a client application includes the system header file Lbs.h and links to the library LbsSelfLocate.dll (LbsSelfLocate.lib).

The following is a brief description of some of the most important API classes:

• RPositionServer is used by client applications to create a session with the location server. This class is also used to get details of the positioning technology modules available and their status. Opening a session with the location server may generate a standard client-server error code which a client application must check for.

• RPositioner is used by client applications to create a subsession with the location server. A client application uses this class to request location information and set the frequency of location information updates. In addition to standard client-server error codes, calls to RPositioner may generate LBS specific error codes (defined in LbsErrors.h) or error codes generated by positioning modules.

• TPositionInfo is a simple data wrapper class. An empty object of this type is passed to RPositioner by a client application when basic location information is required. The returned object holds the identifier of the positioning technology module used to obtain the position data. The position data is held in a TPosition object.

  See Position data and info classes for an overview of the data classes that hold position data.

• TPosition is the class that holds basic position data: latitude, longitude and altitude (and their accuracy) and the time at which the location fix was obtained. See Position data for more information about how co-ordinate values are represented in this class.

Client applications use the API in three ways:

1. To get location information

The main purpose of the Location Acquisition API is to provide location information to client applications.

See How to get location information for an example of how to get basic location information using the API.

2. To get positioning technology module information

The API provides functions to allow discovery of the capabilities and quality of information provided by the set of positioning technology modules.

See Positioning technology modules for a description of the positioning technology module information which is accessible to client applications using the API.

See How to use module information for an example of how to obtain information about the available modules.

See Positioning technology module selection criteria for an explanation of module selection criteria.

See How to use module selection criteria for an example of how to use these criteria to get location information of the required accuracy.

3. To receive notification of positioning technology module status changes

An application may wish to be informed when a module becomes available or unavailable. For example, an application may want to know when GPS becomes available as this may increase its capabilities and so change its behaviour. The API provides a way for client applications to receive notification of module status changes.

See Positioning technology module status for a description of positioning module status and events.

See How to get module status change notifications for an example of how to get notification of module status changes.

Position data and info classes

Positioning technology modules