<?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-5FAF3185-66B3-5783-84FB-1947DCCDEE28"><title>Positioning Indicator API</title><shortdesc>The Positioning Indicator API defines P&amp;S keys for publishing and subscribing for the current status of positioning hardware in the mobile device. The API is deprecated. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>It was intended for use by UI components (such as the UI status bar) that require updates of that status of positioning hardware. The <xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita">Integrated GPS Hardware Status API</xref> now contains an observer class that allows UI components to receive hardware status updates. </p> <section><title>Contents</title> <ul><li id="GUID-2129C0C5-1C66-58AD-82C7-8990B2B4D5CA"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-CBCF690A-3FBE-5A8C-9AAC-E12A4565C6B2">Purpose</xref>  </p> </li> <li id="GUID-69DCEBEE-1F8E-550A-BF02-C5E2AC7C4A08"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-8D6F0FC2-CE3F-576F-BDE6-3015CF1A5B4F">API description</xref>  </p> </li> <li id="GUID-FFA6E3D6-2554-5A05-8DF2-AD8F33FB0423"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-A0B6F0BC-3F89-5985-95C4-3955DF0FFF59">API summary</xref>  </p> </li> <li id="GUID-A83AAD17-B67B-5F75-A8FF-4CB2ACB9875A"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-9A9A272B-955E-5478-AD11-443F5889F842">Using the API</xref>  </p> <ul><li id="GUID-E46D8FD4-1A7D-58CA-A1E7-545BDB27AC91"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-2E136F4D-158C-5FC3-95AD-353C9873D9D3">Updating the state of a </xref> <xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-2E136F4D-158C-5FC3-95AD-353C9873D9D3">positioning UI indicator</xref>  </p> </li> </ul> </li> <li id="GUID-00C55B66-2194-511D-9031-7D32D78149D4"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-E54337E0-5384-5E7A-B166-5D8FA5F173C7">Error handling</xref>  </p> </li> <li id="GUID-907D007F-69A0-56E2-AC10-5478579D51E2"><p><xref href="GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28.dita#GUID-5FAF3185-66B3-5783-84FB-1947DCCDEE28/GUID-C360B60B-3394-5B1A-92DD-097B4915B3DE">See also</xref>  </p> </li> </ul> </section> <section id="GUID-CBCF690A-3FBE-5A8C-9AAC-E12A4565C6B2"><title>Purpose</title> <p>This document describes the Positioning Indicator API. It defines <xref href="GUID-A81C65CF-CF4E-571C-8080-9D387F46AAD6.dita">Publish and Subscribe</xref> (P&amp;S) keys for properties for notifying of changes to GPS hardware status. </p> <p>The API is deprecated. It was intended for use by UI components. The <xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita">Integrated GPS Hardware Status API</xref> is the recommended way of updating UI components with the GPS hardware status. </p> </section> <section id="GUID-8D6F0FC2-CE3F-576F-BDE6-3015CF1A5B4F"><title>API description</title> <p>The API can be used to update UI components when the status of GPS hardware changes. </p> </section> <section id="GUID-A0B6F0BC-3F89-5985-95C4-3955DF0FFF59"><title>API summary</title> <p>The API defines no classes. It defines only global constants which are the Positioning UI Indicator P&amp;S category (<xref href="GUID-73D84B07-DECC-371C-9C83-ED58359C4B0B.dita"><apiname>KPosIndicatorCategory</apiname></xref>) and key (<xref href="GUID-5296D5A3-35E5-35CC-AE76-915D73CC4A65.dita"><apiname>KPosIntGpsHwStatus</apiname></xref>) and an enumeration <xref href="GUID-78564085-1706-3B1D-AE74-9E6E0BC8F799.dita"><apiname>TPosIntGpsHwState</apiname></xref> that defines the values that the P&amp;S property can take. </p> <p>The definitions are in <filepath>locationfwdomainpsKey.h</filepath> are summarised in table 1. </p> <table id="GUID-CAA47900-3E3F-5A10-BEE5-7F60C196315F"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Constant Name</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-73D84B07-DECC-371C-9C83-ED58359C4B0B.dita"><apiname>KPosIndicatorCategory</apiname></xref>  </p> </entry> <entry><p>The UID of Positioning Indicator P&amp;S keys category. </p> </entry> </row> <row><entry><p> <xref href="GUID-5296D5A3-35E5-35CC-AE76-915D73CC4A65.dita"><apiname>KPosIntGpsHwStatus</apiname></xref>  </p> </entry> <entry><p>The ID of the Integrated GPS HW status key. It contain values defined by <xref href="GUID-F948CC28-06B2-3C47-95B0-D1445C37839E.dita"><apiname>TPosIntGpsHwIndicatorState</apiname></xref>. </p> <p>The default value (i.e. when this key is not found) is <xref href="GUID-37710FB3-E772-348B-8551-A8DFB5A565CB.dita"><apiname>EPosIntGpsHwIndicatorOff</apiname></xref>. </p> <p>If it contains any value other than one defined in <xref href="GUID-78564085-1706-3B1D-AE74-9E6E0BC8F799.dita"><apiname>TPosIntGpsHwState</apiname></xref>, the value must be ignored and <xref href="GUID-AE301331-5CE9-39D8-B690-4A03FBCF59E3.dita#GUID-AE301331-5CE9-39D8-B690-4A03FBCF59E3/GUID-5C833EDB-6A2C-3BBE-A99C-EB30CC46E3C2"><apiname>TPosIndicatorState::EPosIntGpsHwIndicatorOff</apiname></xref> must be assumed. </p> </entry> </row> </tbody> </tgroup> </table> <p> <i>Table 1. Positioning IndicatorP&amp;S category and key definitions.</i>  </p> <p><b>Libraries </b> </p> <p>The P&amp;S keys of the Positioning Indicator API are defined in <filepath>locationfwdomainpsKey.h</filepath>. This API uses the Publish and Subscribe API and there are no additional libraries required by a client. </p> <p><b>Capabilities </b> </p> <p>An API client does not require any capabilities to read the property value. </p> </section> <section id="GUID-9A9A272B-955E-5478-AD11-443F5889F842"><title>Using the API</title> <p>This API supports only one typical use case: </p> <p id="GUID-2E136F4D-158C-5FC3-95AD-353C9873D9D3"><b>Updating the state of a positioning UI indicator</b> </p> <p>The API client (a component responsible for updating the status of a UI indicator component) reads the current state of integrated GPS hardware using Publish &amp; Subscribe API (see <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> for details). </p> <p>The client subscribes for changes in <xref href="GUID-5296D5A3-35E5-35CC-AE76-915D73CC4A65.dita"><apiname>KPosIntGpsHwStatus</apiname></xref> P&amp;S key from <xref href="GUID-73D84B07-DECC-371C-9C83-ED58359C4B0B.dita"><apiname>KPosIndicatorCategory</apiname></xref> category. When a state change is reported, a client reads the new value and update UI indicator accordingly. </p> <p>The <xref href="GUID-78564085-1706-3B1D-AE74-9E6E0BC8F799.dita"><apiname>TPosIntGpsHwState</apiname></xref> enumeration defines the possible values of the <xref href="GUID-5296D5A3-35E5-35CC-AE76-915D73CC4A65.dita"><apiname>KPosIntGpsHwStatus</apiname></xref> property. If any other value is retrieved it must be ignored and the value <xref href="GUID-AE301331-5CE9-39D8-B690-4A03FBCF59E3.dita#GUID-AE301331-5CE9-39D8-B690-4A03FBCF59E3/GUID-5C833EDB-6A2C-3BBE-A99C-EB30CC46E3C2"><apiname>TPosIndicatorState::EPosIntGpsHwIndicatorOff</apiname></xref> assumed. If the key is not found, then <codeph>EPosIntGpsHwIndicatorOff</codeph> must be assumed as its value. </p> <p>Figure 1 shows how a client reads and updates UI indicator based on the states of Positioning Indicator P&amp;S key. </p> <fig id="GUID-CE95624C-1E4C-5C3E-A28E-17B45E2CA742"><title>

                Figure 1. Updating the state of Positioning UI Indicator sequence

                diagram 

             </title> <image href="GUID-504C5CD8-DF83-5657-9D38-E94151C84802_d0e459962_href.png" placement="inline"/></fig> <p>Refer to <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> class description in the Symbian platform Reference and "Publish and Subscribe" article in Symbian Guide for further details on using P&amp;S keys. </p> <p>The following table describes the mapping of <xref href="GUID-5296D5A3-35E5-35CC-AE76-915D73CC4A65.dita"><apiname>KPosIntGpsHwStatus</apiname></xref> key values and status of the UI indicator that should be set: </p> <table id="GUID-8E49701A-F83C-59A1-A5FA-89DEE4A24186"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Key value</entry> <entry>Indicator state</entry> <entry>Comment</entry> </row> </thead> <tbody><row><entry><p> <codeph>TPosIndicatorState::EPosIntGpsHwOff</codeph>  </p> </entry> <entry><p>Hidden </p> </entry> <entry><p>GPS hardware is OFF and indicator should be hidden. </p> </entry> </row> <row><entry><p> <codeph>TPosIndicatorState::EPosIntGpsHwOn</codeph>  </p> </entry> <entry><p>Shown </p> </entry> <entry><p>GPS hardware is ON and indicator should be shown. </p> </entry> </row> <row><entry><p> <codeph>TPosIndicatorState::EPosIntGpsHwIntermediate</codeph>  </p> </entry> <entry><p>Animated </p> </entry> <entry><p>GPS hardware in intermediate state. UI indicator is shown in intermediate (possibly animated) state. </p> </entry> </row> </tbody> </tgroup> </table> </section> <section id="GUID-E54337E0-5384-5E7A-B166-5D8FA5F173C7"><title>Error handling</title> <p>This API does not define or use any error codes. </p> <p>Refer to <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> class description in the Symbian platform Reference for further details on error handling in Publish &amp; Subscribe API. </p> </section> <section id="GUID-C360B60B-3394-5B1A-92DD-097B4915B3DE"><title>See also</title> <p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita">Integrated GPS Hardware Status API</xref>  </p> </section> </conbody></concept>