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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

    15 <section><title>Purpose</title> <p>This document describes the Location Acquisition

    16 API. Client applications use the API to obtain the location of the mobile

    17 device and to discover the type and status of the available Positioning Modules. </p> </section>

    18 <section><title>Introduction</title> <p>The Location Acquisition API defines

    19 the client application view of the LBS Location Server. The API is a standard

    20 Symbian platform client/server implementation. Applications use the API to: </p> <ul>

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

    22 of the mobile device </p> <p>The Location Acquisition API is designed so that

    23 client applications can always make the same API calls to obtain the device

    24 location irrespective of the underlying positioning technologies used by the

    25 Location Server. </p> </li>

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

    27 status of available positioning technologies </p> <p>The API allows applications

    28 to discover the available Positioning Modules and to receive notification

    29 of changes in their status. Applications can also make a choice of the specific

    30 Positioning Module to use to get the device location. </p> </li>

    31 </ul> </section>

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

    33 <dlentry>

    34 <dt>Location Server</dt>

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

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

    37 location information. </p> </dd>

    38 </dlentry>

    39 <dlentry>

    40 <dt>Positioning Module</dt>

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

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

    43 </dlentry>

    44 </dl> </section>

    45 <section><title>API summary</title> <p>Figure 1 illustrates the client interface

    46 classes of the Location Acquisition API including the data classes that hold

    47 basic location information. The classes shown are defined in the header file <filepath>lbs.h</filepath>.

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

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

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

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

    52 used by client applications to create a session with the Location Server.

    53 This class is also used to get details of the positioning technology modules

    54 available and their status. Opening a session with the Location Server may

    55 generate a standard client/server error code which a client application must

    56 check for. </p> </li>

    57 <li id="GUID-B6A6ECBF-1FF9-505A-8B45-8968DA1612AC"><p> <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> is

    58 used by client applications to create a subsession with the Location Server.

    59 A client application uses this class to request location information and set

    60 the frequency of location information updates. In addition to standard client/server

    61 error codes, calls to <codeph>RPositioner</codeph> may generate LBS specific

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

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

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

    65 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

    66 a client application when basic location information is required. The returned

    67 object holds the identifier of the positioning technology module used to obtain

    68 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

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

    70 <li id="GUID-CED05369-EC6E-5C0D-AAD5-1A34A2BFFA7E"><p> <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> is

    71 the class that holds basic position data: latitude, longitude and altitude

    72 (and their accuracy) and the time at which the location fix was obtained.

    73 See <xref href="GUID-AD7D9D39-6FF0-5811-9708-98538271BA0D.dita">Position data</xref> for

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

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

    76 <title>              Figure 1. RPositionServer and RPositioner with basic

    77 position data              classes            </title>

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

    79 </fig> </section>

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

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

    82 API. </p> </section>

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

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

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

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

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

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

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

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

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

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

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

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

    95 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

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

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

    98 of positioning technology module status changes. </p> <p>An application may

    99 wish to be informed when a module becomes available or unavailable. For example,

   100 an application may want to know when GPS becomes available as this may increase

   101 its capabilities and so change its behaviour. The API provides a way for client

   102 applications to receive notification of module status changes. </p> <p>See <xref href="GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita">Positioning technology module

   103 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

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

   105 status changes. </p> </li>

   106 </ol> </section>

   107 </conbody><related-links>

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

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

   110 </related-links></concept>