<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741" xml:lang="en"><title>Location

Acquisition API Overview</title><shortdesc>Applications use the Location Acquisition API to obtain location

fixes from the LBS subsystem. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p>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. </p> </section>

<section><title>Introduction</title> <p>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: </p> <ul>

<li id="GUID-600F2A1E-DADF-5172-B1FC-A3C2190E61DF"><p>Obtain the location

of the mobile device </p> <p>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. </p> </li>

<li id="GUID-A6480A42-E1FF-5DAF-8F1E-3C490D9332E5"><p>Discover the type and

status of available positioning technologies </p> <p>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. </p> </li>

</ul> </section>

<section><title>Key concepts</title> <dl>

<dlentry>

<dt>Location Server</dt>

<dd><p>The Symbian platform server used by client applications to get location

information. The Location Server can use multiple Positioning Modules to obtain

location information. </p> </dd>

</dlentry>

<dlentry>

<dt>Positioning Module</dt>

<dd><p>An ECom plug-in that handles requests for location information and

interfaces with positioning technology hardware. </p> </dd>

</dlentry>

</dl> </section>

<section><title>API summary</title> <p>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 <filepath>lbs.h</filepath>.

See <xref href="GUID-0D5692FB-305E-58B2-B105-B309BB9AE38D.dita">Location Acquisition

API reference</xref> for a full list of all the API header files. </p> <p>The

following is a brief description of some of the most important API classes: </p> <ul>

<li id="GUID-CBE6C60B-B28F-5CBC-93BE-E7DC8E2CE678"><p> <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita"><apiname>RPositionServer</apiname></xref> 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. </p> </li>

<li id="GUID-B6A6ECBF-1FF9-505A-8B45-8968DA1612AC"><p> <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> 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 <codeph>RPositioner</codeph> may generate LBS specific

error codes (defined in <filepath>LbsErrors.h</filepath>) or error codes generated

by Positioning Modules. </p> </li>

<li id="GUID-EB6A67CE-5F09-5A9E-86FE-D2A3337B6FD9"><p> <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> is

a simple data wrapper class. An empty object of this type is passed to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> 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 <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> object. </p> <p>See <xref href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita">Position data and info classes</xref> for

an overview of the data classes that hold position data. </p> </li>

<li id="GUID-CED05369-EC6E-5C0D-AAD5-1A34A2BFFA7E"><p> <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> 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 <xref href="GUID-AD7D9D39-6FF0-5811-9708-98538271BA0D.dita">Position data</xref> for

more information about how co-ordinate values are represented in this class. </p> </li>

</ul> <fig id="GUID-4F3214DA-0D42-5FFB-8392-3A29F743E6F6">

<title>              Figure 1. RPositionServer and RPositioner with basic

position data              classes            </title>

<image href="GUID-E86347E8-8D3C-5FCB-BD9F-EA0DF8F0D9FD_d0e266235_href.png" placement="inline"/>

</fig> </section>

<section><title>Platform security capabilities</title> <p>Applications must

have the <codeph>Location</codeph> capability to use the Location Acquisition

API. </p> </section>

<section><title>Typical uses</title> <p> <i>Client applications use the API

in three ways:</i>  </p> <ol id="GUID-B37E7969-ADCE-56FD-ADE6-6A0D85A6C608">

<li id="GUID-E04AA9F3-2013-5F64-B880-01BAE092F07C"><p>To get location information. </p> <p>The

main purpose of the Location Acquisition API is to provide location information

to client applications. </p> <p>See <xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How

to get location information</xref> for examples of how to get basic location

information using the API. </p> </li>

<li id="GUID-25454FD2-14E2-590E-B520-D1241046E24D"><p>To get positioning technology

module information. </p> <p>The API provides functions to allow discovery

of the capabilities and quality of information provided by the set of positioning

technology modules. </p> <p>See <xref href="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita">Positioning

technology modules</xref> for a description of the positioning technology

module information which is accessible to client applications using the API. </p> <p>See <xref href="GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita">How to use module information</xref> for

an example of how to obtain information about the available modules. </p> </li>

<li id="GUID-558D8BE4-E8B9-55B7-9CA5-10A35B0D2664"><p>To receive notification

of positioning technology module status changes. </p> <p>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. </p> <p>See <xref href="GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita">Positioning technology module

status</xref> for a description of Positioning Module status and events. </p> <p>See <xref href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita">How to get module status

change notifications</xref> for an example of how to get notification of module

status changes. </p> </li>

</ol> </section>

</conbody><related-links>

<link href="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita"><linktext>Position

Data and Info Classes</linktext></link>