<?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 xml:lang="en" id="GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D"><title>Position data and info classes</title><shortdesc>This document describes the basic and extended classes that hold position data. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Location Acquisition API defines a set of position data classes. Some of these classes store the co-ordinates of a location fix and others store information about course and positioning satellites. The API also defines position info classes that wrap the position data classes. These classes are used to pass data across the Location Acquisition API. Figure 1 illustrates the position data and position info classes with some of the most important methods. </p> <fig id="GUID-F94FF72F-D6F3-5913-BAEF-CF6B682A27D6"><title>

          Figure 1 Position data and info classes 

        </title> <image href="GUID-3B2957D0-4D1A-5289-BE2A-AC8CD34A54E6_d0e446405_href.png" placement="inline"/></fig> <section><title>The position data classes</title> <ul><li id="GUID-4C4B6DB7-B417-5505-8F02-B27102922E8D"><p> <xref href="GUID-DDCBA817-9D88-3332-ABD3-1DDC6E397851.dita"><apiname>TCoordinate</apiname></xref> is the base class for all the position data classes. It holds latitude, longitude and altitude data. All positioning modules must provide latitude and longitude information, but not all modules are guaranteed to provide altitude information. </p> </li> <li id="GUID-B8698831-583A-5527-A5F4-2FCB264CA97F"><p> <xref href="GUID-17A40F7C-E4CD-3F82-832A-AA8142973053.dita"><apiname>TLocality</apiname></xref> adds accuracy information to co-ordinates. </p> </li> <li id="GUID-87EC3A5C-FE30-5D79-9025-64153337CF85"><p> <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> adds the time at which the location fix was obtained and also allows the average speed between two positions to be calculated. </p> </li> </ul> <p>There are two additional position data classes that are not part of this position data class inheritance hierarchy. </p> <ul><li id="GUID-CCE8AC41-C64D-5CB3-8297-4CB5E319080B"><p> <xref href="GUID-E66165C3-6391-39CF-BF88-99A61D69E6FA.dita"><apiname>TCourse</apiname></xref> holds bearing and current speed data. </p> </li> <li id="GUID-A214CDDF-8823-5F61-87C8-0537809A5F8F"><p> <xref href="GUID-5440B1A0-98B0-3689-AC0B-27D5A35BFDA1.dita"><apiname>TSatelliteData</apiname></xref> holds information on one of the satellites used to obtain the location fix. </p> </li> </ul> <p>Note that it is a position info object and not a position data object that is passed across the Location Acquisition API. Client applications extract the position data object from the wrapper position info object. </p> <p>See <xref href="GUID-AD7D9D39-6FF0-5811-9708-98538271BA0D.dita">Position data</xref> for a description of how the location data is represented inside the position data classes. </p> </section> <section><title>The position info classes</title> <p>Client applications use three position info classes that wrap the position data classes: </p> <ul><li id="GUID-E5BF9465-73F0-5F88-9D26-F74061DC14EB"><p> <xref href="GUID-D5B2E933-209D-3871-8E27-CC5C8855C745.dita"><apiname>TPositionInfo</apiname></xref> wraps a <xref href="GUID-AB9F288E-86C6-327A-9E53-2EA746416038.dita"><apiname>TPosition</apiname></xref> class </p> </li> <li id="GUID-C65D7549-456B-5AE1-B3E4-5ED7A0F1888A"><p> <xref href="GUID-B4CD3637-0FC6-38B8-AE89-C03EEC83C50D.dita"><apiname>TPositionCourseInfo</apiname></xref> wraps a <xref href="GUID-E66165C3-6391-39CF-BF88-99A61D69E6FA.dita"><apiname>TCourse</apiname></xref> class </p> </li> <li id="GUID-B333B4A1-3D91-5C4A-9711-836769CB4B59"><p> <xref href="GUID-54AE0674-C49D-3329-8B77-3A58EFFC03D7.dita"><apiname>TPositionSatelliteInfo</apiname></xref> wraps a <xref href="GUID-5440B1A0-98B0-3689-AC0B-27D5A35BFDA1.dita"><apiname>TSatelliteData</apiname></xref> class </p> </li> </ul> <p>To get location information, a reference to an object of a class derived from <xref href="GUID-73D6F438-C270-33B9-974B-D4D1583E1738.dita"><apiname>TPositionInfoBase</apiname></xref> is passed in a call to <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref> or <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-D9E0BC1D-7783-35BA-8D88-223576E4C85E"><apiname>RPositioner::GetLastKnownPosition()</apiname></xref>. The position info class hierarchy allows simple location information (<codeph>TPositionInfo</codeph>), course information (<codeph>TCourse</codeph> Info) or satellite information (<codeph>TSatelliteInfo</codeph>) to be obtained via the same calls to the Location Acquisition API. </p> <p><b>HPositionGenericInfo</b> </p> <p> <xref href="GUID-C0D87E5C-315E-37E6-829E-73F93E83748E.dita"><apiname>HPositionGenericInfo</apiname></xref> is an extended position info class that allocates memory on the heap. Applications can use the class to retrieve additional position information from positioning hardware that can provide it (such as NMEA strings provided by Bluetooth GPS hardware). </p> <p> <codeph>HPositionGenericInfo</codeph> is only supported by the Location Server <codeph>eposserver.exe</codeph>. It can only be used by applications that link with <filepath>lbs.lib</filepath>. Not all PSYs support this class. </p> </section> <section><title>See also</title> <p><xref href="GUID-AD7D9D39-6FF0-5811-9708-98538271BA0D.dita">Position data</xref>  </p> </section> </conbody></concept>