Location Acquisition API overview in The Location Acquisition API

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 modules and to receive notification of changes in their status. Applications can also make a choice of the specific positioning 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 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. The classes shown are defined in the header file lbs.h. See Location Acquisition API reference for a full list of all the API header files.

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.

Applications must have the Location capability to use the Location Acquisition API.

Figure 1. RPositionServer and RPositioner with basic position data classes

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

An early version of the Location Acquisition API was first introduced in the S60 platform version 2.6. Although this was based on Symbian OS version 8.x the API was not supported on other UI platforms. The first version of the API that was available on all UI platforms was introduced in Symbian OS version 9.2.

Although the two versions of the interface have a common set of classes and use the same header files, it is necessary for developers to link their application against different libraries:

To use the Location Acquisition API on the S60 platform applications must link against the library lbs.dll (import library lbs.lib).
On other UI platforms, applications must link against the library lbsselflocate.dll (import library lbsselflocate.lib).

There are also some other minor differences that should be noted and are described in the table below. Further details are documented in How to get location information.

LBS behaviour	Client library is lbsselflocate.dll	Client library is lbs.dll
Application is for non-S60 platform	Link application code with `lbsselflocate.lib`	Do not link with this library
Application is for S60 platform	Do not link with this library	Link application code with `lbs.lib`
Support for class `HPositionGenericInfo`	Not supported (do not use)	Supported
`RPositioner::CompleteRequest()`	Supported	Not supported (returns `KErrNotSupported`)
Calls to `RPositioner::SetRequestorL()`	Optional - calling this method is not required	Method call is required