<?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-1D81831A-FFC9-50E7-9FA1-EC0958060588"><title>Bluetooth GPS PSY Events API Overview</title><shortdesc>The Bluetooth GPS PSY Events API uses the Publish and Subscribe (P&amp;S) service to notify clients about the state of the PSY and the connected Bluetooth GPS device. The API is for developers who write components to notify users of changes in the Bluetooth GPS PSY state. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>A client of this API would typically be a UI component that reports the status of the Bluetooth GPS PSY to a device user. The component would typically be a Notifier or a UI component in a status bar. </p> </section> <section><title>Library details</title> <p>This API consists of a set of P&amp;S keys defined in the header file <filepath>BtGpsPsyPrivatePSKeys.h</filepath>. Applications must link with <codeph>euser.lib</codeph>  <codeph/>to use this API. </p> </section> <section id="GUID-8901A822-7CD5-5023-88B9-F912BEC0086D"><title>Description</title> <p id="GUID-96A15FD9-025B-54C7-97BC-5FA1518FA83C"><b>Use cases</b> </p> <p>The use cases of this API are: </p> <ul><li id="GUID-A28956BB-4A79-5BC7-A7F3-7722EC69DAB7"><p>Listening for changes in state of the Bluetooth GPS PSY and the connected Bluetooth GPS device. </p> </li> <li id="GUID-19F54031-565F-54C8-92F7-0C07D92D62F0"><p>Retrieving the current state of the Bluetooth GPS PSY. </p> </li> </ul> <p id="GUID-739D861D-8BE9-5BFD-81AE-4F7D8E5536CA"><b>API class structure</b> </p> <p>This API doesn’t define any classes. It defines a Bluetooth GPS PSY events P&amp;S category <xref href="GUID-8E951395-C57E-3F23-AB0D-CAF24343B935.dita"><apiname>KPsUidBluetoothGpsPsy</apiname></xref>, some keys and some enumerated types for key values. These are defined in the <filepath>BtGpsPsyPrivatePSKeys.h</filepath>. </p> </section> <section id="GUID-DA9B90A9-DAE4-5995-9790-528C622B0BA3"><title>Using the Bluetooth GPS PSY Events API</title> <p>To listen for Bluetooth GPS PSY state changes, clients subscribe for notifications of changes in P&amp;S keys from the <xref href="GUID-8E951395-C57E-3F23-AB0D-CAF24343B935.dita"><apiname>KPsUidBluetoothGpsPsy</apiname></xref> category. When a state change is reported, the client reads the new value and can respond to the change event (such as by showing a dialog to the user). An API client does not require any capabilities to read key values. </p> <p>See <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita">Using Publish and Subscribe</xref> for details of how to get key values and subscribe for notification of value changes. </p> <p>The following table describes Bluetooth GPS PSY P&amp;S keys and values which are defined in <filepath>BtGpsPsyPrivatePSKeys.h</filepath>. </p> <table id="GUID-06E6ECA2-9C6B-50DB-9292-671B76319CC1"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Keys</entry> <entry>Description</entry> <entry>Possible values</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-DD9E328E-D841-394B-B52D-092D23D2B7AE.dita"><apiname>KBluetoothGpsPsyState</apiname></xref>  </p> </entry> <entry><p>The current state of the PSY. </p> </entry> <entry><p>Whether the PSY is loaded and whether it is connected to a particular type of device (PNOK or non PNOK) etc. </p> <p>Defined by <xref href="GUID-F28631C5-711C-3943-803C-FA659AD9CDBD.dita"><apiname>TBTGPSPSYState</apiname></xref>. </p> </entry> </row> <row><entry><p> <xref href="GUID-8DAAA1F1-05E4-3A4A-87B5-86C2E6BEDE5E.dita"><apiname> KBluetoothGpsPsyBatteryLevel</apiname></xref>  </p> </entry> <entry><p>The battery charge remaining in the Bluetooth GPS device. </p> </entry> <entry><p>A value between 0-100 (100 means battery is full) </p> </entry> </row> <row><entry><p> <xref href="GUID-B17D619A-91FA-3E6E-80D4-EFEF5898979E.dita"><apiname> KBluetoothGpsPsyBatteryState</apiname></xref>  </p> </entry> <entry><p>The battery charge remaining in the Bluetooth GPS device represented in three different bands: </p> <ul><li id="GUID-67A699BC-B9EB-5266-8AD7-0C45FE0AAD28"><p>Low: voltage level &lt; 10% </p> </li> <li id="GUID-32328D4E-9348-50C4-8356-3B9DC7CB724F"><p>High: voltage level &gt; 90% </p> </li> <li id="GUID-37933EDE-3FA1-5C4B-82E4-66F7CAD9F029"><p>Normal: voltage level 10%-90%. </p> </li> </ul> </entry> <entry><p>Defined by <xref href="GUID-53DF8A44-47B4-3EC4-B7BF-FE11C2226102.dita"><apiname>TBTGPSBatteryState</apiname></xref>. </p> </entry> </row> <row><entry><p> <xref href="GUID-118FD9B6-22DD-3621-9502-BE4526CE7EF8.dita"><apiname> KBluetoothGpsPsyExtAntennaState</apiname></xref>  </p> </entry> <entry><p>Whether an external antenna is connected to Bluetooth GPS device. </p> <p>An external antenna can be connected to a GPS device when it is in an environment where the GPS signal is weak or blocked. </p> </entry> <entry><p>Defined by <xref href="GUID-2587BFB7-E7C0-3B78-9494-F8FBC16DE508.dita"><apiname>TBTGPSExtAntennaState</apiname></xref>. </p> </entry> </row> <row><entry><p> <xref href="GUID-06B16896-9C2E-3EBF-A701-A377055EDC78.dita"><apiname>KBluetoothGpsPsyExtPowerState</apiname></xref>  </p> </entry> <entry><p>Whether a battery charger is connected to the Bluetooth GPS device. </p> </entry> <entry><p>Defined by <xref href="GUID-8B3DE9EF-B163-3C00-8799-A6D53A0B1196.dita"><apiname>TBTGPSExtPowerState</apiname></xref>. </p> </entry> </row> <row><entry><p> <xref href="GUID-673A43DB-EAE9-37A5-9465-7BD69DD6470B.dita"><apiname>KBluetoothGpsPsyVersion</apiname></xref>  </p> </entry> <entry><p>Version of Bluetooth GPS PSY currently in use. </p> </entry> <entry><p>Descriptor with maximum length 32. </p> </entry> </row> <row><entry><p> <xref href="GUID-BF9130DC-B3BB-335A-94FB-6C1352162F36.dita"><apiname> KBluetoothGpsPsyBtHwVersion</apiname></xref>  </p> </entry> <entry><p>Version of Bluetooth hardware in the Bluetooth GPS device. </p> </entry> <entry><p>Descriptor with maximum length 32. </p> <p> </p> </entry> </row> <row><entry><p> <xref href="GUID-6C53B9F4-3537-38A6-A59B-497AAC734E64.dita"><apiname>KBluetoothGpsPsyBtSwVersion</apiname></xref>  </p> </entry> <entry><p>Version of Bluetooth software in the Bluetooth GPS device. </p> </entry> <entry><p>Descriptor with maximum length 32. </p> </entry> </row> <row><entry><p> <xref href="GUID-9905E244-9E97-3690-A870-3B79C4E7205A.dita"><apiname> KBluetoothGpsPsyGpsHwVersion</apiname></xref>  </p> </entry> <entry><p>Version of GPS chipset in the Bluetooth GPS device. </p> </entry> <entry><p>Descriptor with maximum length 32. </p> </entry> </row> <row><entry><p> <xref href="GUID-CAC8CE54-DF10-3190-97B0-840F850AE21A.dita"><apiname>KBluetoothGpsPsyGpsSwVersion</apiname></xref>  </p> </entry> <entry><p>Version of GPS software in the Bluetooth GPS device. </p> </entry> <entry><p>Descriptor with maximum length 32. </p> </entry> </row> </tbody> </tgroup> </table> <p id="GUID-626F69E4-730F-55EE-A93C-B050ED6A11CC"><b>Listening for changes in the state of Bluetooth GPS PSY</b> </p> <p>Figure 1 is a sequence diagram describing notifications to the client about Bluetooth GPS PSY state changes. </p> <fig id="GUID-6DEDC4E6-97DD-513A-BBC1-A4EA24521B1F"><title>

                Figure 1. Registering for and receiving Bluetooth GPS device state

                change events. 

             </title> <image href="GUID-147C77CB-16A1-548B-A1C7-05F2C5FF9E27_d0e462630_href.png" placement="inline"/></fig> <p id="GUID-0FD168EE-E566-5C33-B1C0-84594659410B"><b>Retrieving current state of Bluetooth GPS PSY</b> </p> <p>Figure 2 shows a sequence diagram that describes retrieval of the current state of Bluetooth GPS PSY. </p> <fig id="GUID-E44DF87A-B4A7-5793-8B78-0437450B1FB6"><title>

                Figure 2. Getting the current value of a Bluetooth GPS property. 

             </title> <image href="GUID-D5707217-DE3F-551D-82C9-C82D3047D90E_d0e462644_href.png" placement="inline"/></fig> <p id="GUID-B6C7FF94-5CCB-5434-9EC3-9DFCF3E01CE5"><b>Error handling</b> </p> <p>The Bluetooth GPS PSY Events API does not define or use any error codes. Refer to the <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita"><apiname>RProperty</apiname></xref> class description in reference documentation for further details on error handling when using Publish and Subscribe. </p> <p id="GUID-9BCD48ED-CAA1-57D5-8DE0-A05FA1BFE2F9"><b>Memory overhead</b> </p> <p>The Bluetooth GPS PSY Events API does not require any additional memory above that needed for normal use of Publish and Subscribe. </p> </section> </conbody><related-links><link href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita"><linktext>Using Publish and Subscribe</linktext> </link> <link href="GUID-F84E7419-7F31-5E18-8854-27CB1F9F890E.dita"><linktext>Bluetooth