<?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-01299529-4390-5C16-8459-1D9C1B6F3EF3"><title>GEO Property</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Geographic Position property is identified by the name GEO. This property specifies information related to the global position of the 'home' system that created the vCalendar or iCalendar object. The property value specifies longitude and latitude. The longitude represents the location east and west of the prime meridian as a positive or negative real number, respectively. The latitude represents the location north and south of the equator as a positive or negative real number, respectively. </p> <p>The latitude and longitude values may have a maximum precision of up to 6 decimal places, which will be truncated depending on the support by the accepting application. </p> <p>Latitude values are restricted to be from 0 to 90 and longitude values from 0 to 180. Clients will not be able to specify any value outside of this range. </p> <p>This GEO property must contain two floating number parameters – one for latitude and the other for the longitude of the entry’s global position. </p> <p>Here is an example of a GEO property in a vCalendar file: </p> <ul><li id="GUID-10156669-90FA-588F-BC0F-84470752F232"><p>GEO:37.24,-17.87 </p> </li> </ul> <p>Here are examples of GEO property in an iCalendar file: </p> <ul><li id="GUID-DAF32538-53F7-5C84-835F-CC67CE5AFEDB"><p>GEO:37.386013;-122.082932 </p> </li> </ul> <ul><li id="GUID-912F7DE9-908B-51B3-88DE-BDBBF985FE20"><p>GEO:28.55;36.22 </p> </li> </ul> <ul><li id="GUID-33A7CB6B-F6DD-5BCC-A0E0-45841B52964B"><p>GEO:-43.003241;-161.039483 </p> </li> </ul> <p>As can be seen, there is a subtle difference in the way the GEO property is displayed between the iCalendar and vCalendar specifications. The delimiter is a semi-colon in iCalendar as opposed to a comma in vCalendar. </p> <section><title>Setting a GEO Property</title> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalGeoValue::SetLatLongL(const TReal&amp; aLatitude, const
          TReal&amp; aLongitude)</apiname></xref> sets the latitude and longitude positions for the geographical location. </p> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>aLatitude</apiname></xref> stores the latitude in degrees. Minutes are represented as a decimal fraction, rounded to 6 decimal places. Latitude may range from -90 to 90. A positive latitude indicates a position north of the equator, while a negative latitude is south of it. </p> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>aLongitude</apiname></xref> stores the longitude in degrees. Minutes are represented as a decimal fraction rounded to 6 decimal places. Longitude ranges from -180 to 180. A positive longitude indicates a position east of the prime meridian, while a negative longitude is a position west of it. </p> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>KErrArgument</apiname></xref> error occurs if the latitude or longitude is out of range </p> </section> <section><title>Getting a GEO Property</title> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalGeoValue::GetLatLong(TReal&amp; aLatitude, TReal&amp;
          aLongitude)</apiname></xref> gets the latitude and longitude positions for the geographical location. </p> <p>On return, <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>aLatitude</apiname></xref> contains the value of the latitude in degrees. Minutes are represented as a decimal fraction. Latitude may be from -90 to 90. A positive latitude indicates a position north of the equator. </p> <p>On return, <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>aLongitude</apiname></xref> contains the value of the longitude in degrees. Minutes are represented as a decimal fraction. Longitude may be from -180 to 180. A positive longitude indicates a position east of the prime meridian. </p> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>EFalse</apiname></xref> is returned if the latitude and longitude have not been set on this object. <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>ETrue</apiname></xref> is returned if they have been set and are both valid. </p> </section> <section><title>Setting a Geographic Location</title> <p>Once a geographical location object (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalGeoValue</apiname></xref>) has been created, <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::SetGeoValueL(const CCalGeoValue&amp;
          aGeoValue)</apiname></xref> sets the geographic location for this entry. This is known as the GEO property in vCalendar and iCalendar. Note that if the latitude and longitude are not set, then the GEO property will be reset on this entry. </p> </section> <section><title>Getting a Geographic Location</title> <p> <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalEntry::GeoValueL()</apiname></xref> gets the geographic location for this entry, known as the GEO property in vCalendar and iCalendar (RFC 2445). It returns a new <xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalGeoValue</apiname></xref> object which contains the geographic location. </p> <p>A geographical location object (<xref href="GUID-725D11A2-8805-3466-98DB-EF5CDEAF2801.dita"><apiname>CCalGeoValue</apiname></xref>) is now created, containing the entry's GEO values if they are present. If they are not present, nothing happens and NULL is returned. </p> </section> </conbody></concept>