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

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.

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.