Location -Acquisition API Overview

Location -Acquisition API OverviewApplications use the Location Acquisition API to obtain location -fixes from the LBS subsystem. -

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.

-Position -Data and Info Classes + + + + + +Location +Acquisition API OverviewApplications use the Location Acquisition API to obtain location +fixes from the LBS subsystem. +

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.

+Position +Data and Info Classes

\ No newline at end of file