Location +Acquisition API Overview

Purpose

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.

Introduction

The Location Acquisition API defines +the client application view of the LBS Location Server. The API is a standard +Symbian platform 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.

Key concepts

Location Server: The Symbian platform server used by client applications to get location +information. The Location Server can use multiple Positioning Modules to obtain +location information.
Positioning Module: An ECom plug-in that handles requests for location information and +interfaces with positioning technology hardware.

API summary

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.

+ Figure 1. RPositionServer and RPositioner with basic +position data classes + +

Platform security capabilities

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

Typical uses

Client applications use the API +in three ways:

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