<?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>
</related-links></concept>