Symbian3/SDK/Source/GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Wed, 31 Mar 2010 11:11:55 +0100
changeset 7 51a74ef9ed63
child 8 ae94777fff8f
permissions -rw-r--r--
Week 12 contribution of API Specs and fix SDK submission
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<concept id="GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA" xml:lang="en"><title>Position
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    13
Area Data Classes</title><shortdesc>This document describes the basic and extended position area data
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    14
classes that contain information about the accuracy of the position returned
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    15
to an application when it calls <codeph>RPositioner::GetLastKnownPositionArea()</codeph>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    16
<p>LBS maintains a cache of previously calculated position fixes. If an application
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    17
calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-BF3BBDC5-8B12-3374-ACEB-4013E9CFEBEF"><apiname>RPositioner::GetLastKnownLocation()</apiname></xref>, LBS returns
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    18
the most recently calculated position. If an application calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-A8484963-B2C4-339D-AF8C-056792444D89"><apiname>RPositioner::GetLastKnownPositionArea()</apiname></xref>,
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    19
LBS returns the position fix that is the best match for the current location
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    20
of the mobile device. The current location of the mobile device is estimated
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    21
from data received from the network. </p>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    22
<p>The Location Acquisition API defines a set of position area data classes
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    23
(figure 1). A client application passes an object of one of these classes
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    24
as a parameter when it calls <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-A8484963-B2C4-339D-AF8C-056792444D89"><apiname>RPositioner::GetLastKnownPositionArea()</apiname></xref>.
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    25
The position area data classes are defined in <filepath>LbsAreaInfo.h</filepath>. </p>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    26
<fig id="GUID-898DA2B8-185E-5906-803A-1871320A0F7E">
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    27
<title>           Figure 1. Position Area Data Classes.          </title>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    28
<image href="GUID-4930A22F-EF80-5B08-A878-C0DB73929558_d0e270258_href.png" placement="inline"/>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    29
</fig>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    30
<p>A brief description of the classes follows. Follow the links to more detailed
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    31
reference documentation. </p>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    32
<ul>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    33
<li id="GUID-6EFEC1C0-FA51-5700-AF45-C25F69C8FF34"><p> <xref href="GUID-4AD8EC91-7272-3ABA-92AB-E299E85FDC6D.dita"><apiname>TPositionAreaInfoBase</apiname></xref> is
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    34
the base class of the position area data classes. Applications create an object
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    35
of one of the derived classes. </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    36
<li id="GUID-0F54B61E-D87A-5014-8808-863323BBD475"><p> <xref href="GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773.dita"><apiname>TPositionAreaInfo</apiname></xref> contains
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    37
basic information about the accuracy of a returned position. Its defines an
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    38
enumerated type <xref href="GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773.dita#GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773/GUID-3B9DEDE6-8903-3B26-9CE6-19D6B4833309"><apiname>TPositionAreaInfo::_TArea</apiname></xref> that defines
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    39
an estimate of how closely the current device position matches the returned
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    40
position. The position accuracy estimate can be from country level down to
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    41
street level, depending on how much information is available from the network. </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    42
<li id="GUID-7ADA8994-7028-5C76-9870-FB0F4AA82F82"><p> <xref href="GUID-BC7DEDAF-80AE-34DC-8FD8-CF77FA511B3D.dita"><apiname>TPositionAreaExtendedInfo</apiname></xref> extends <codeph>TPositionAreaInfo</codeph> to
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    43
provide details about how the accuracy estimate of the returned position was
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    44
calculated. </p> <p>An accuracy estimate can be obtained from the network
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    45
as some combination of the following: </p> <ul>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    46
<li id="GUID-AA4BFDD9-D024-5F1C-873C-55A18AC7EB10"><p>Mobile Country Code </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    47
<li id="GUID-7AEE15CD-33B2-5833-BE64-8E2D2C729DF4"><p>Mobile Network Code </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    48
<li id="GUID-4666634D-05C4-59C1-AD51-55A28F67DC3B"><p>Location Area Code </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    49
<li id="GUID-B3BEE4FC-8955-5FAC-B382-121F49C8D1D7"><p>Cell ID </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    50
</ul> <p>LBS uses combinations of the above to derive the accuracy estimate
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    51
returned from <xref href="GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773.dita#GUID-5FA78254-70C7-3105-B6CE-E1A294C8F773/GUID-C8B19BA7-72A0-35CD-AF72-AD74E9C0CE5B"><apiname>TPositionAreaInfo::Area()</apiname></xref>. Your application
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    52
can find what types of data were used to calculate the accuracy estimate by
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    53
passing an object of class <xref href="GUID-BC7DEDAF-80AE-34DC-8FD8-CF77FA511B3D.dita"><apiname>TPositionAreaExtendedInfo</apiname></xref> to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-A00A1673-10F2-357A-A3CA-FFB4E14F2F8D"><apiname>RPositioner::GetLastKnownLocationArea()</apiname></xref> and
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    54
then using the methods shown in figure 1 to check for code and ID matches. </p> </li>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    55
</ul>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    56
</conbody><related-links>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    57
<link><linktext/></link>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    58
<link href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita"><linktext>How to Get
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    59
Location Information</linktext></link>
51a74ef9ed63 Week 12 contribution of API Specs and fix SDK submission
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    60
</related-links></concept>