![Symbian Developer Library](../../../../../a_stock/images/mainheading.gif)
![]() |
![]() |
|
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.
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.
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.
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.
Client applications use the API in three ways:
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.
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.
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 |
Do not link with this library |
Application is for S60 platform |
Do not link with this library |
Link application code with |
Support for class |
Not supported (do not use) |
Supported |
|
Supported |
Not supported (returns |
Calls to |
Optional - calling this method is not required |
Method call is required |