Bluetooth GPS PSY Events API Overview
The Bluetooth GPS PSY Events API uses the Publish and Subscribe (P&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.
Purpose
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.
Library details
This API consists of a set of P&S keys defined in the header file BtGpsPsyPrivatePSKeys.h. Applications must link with euser.lib to use this API.
Description
The use cases of this API are:
Listening for changes in state of the Bluetooth GPS PSY and the connected Bluetooth GPS device.
Retrieving the current state of the Bluetooth GPS PSY.
This API doesn’t define any classes. It defines a Bluetooth GPS PSY events P&S category KPsUidBluetoothGpsPsy, some keys and some enumerated types for key values. These are defined in the BtGpsPsyPrivatePSKeys.h.
Using the Bluetooth GPS PSY Events API
To listen for Bluetooth GPS PSY state changes, clients subscribe for notifications of changes in P&S keys from the KPsUidBluetoothGpsPsy 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.
See Using Publish and Subscribe for details of how to get key values and subscribe for notification of value changes.
The following table describes Bluetooth GPS PSY P&S keys and values which are defined in BtGpsPsyPrivatePSKeys.h.
| Keys | Description | Possible values |
|---|---|---|
The current state of the PSY. |
Whether the PSY is loaded and whether it is connected to a particular type of device (PNOK or non PNOK) etc. Defined by TBTGPSPSYState. |
|
The battery charge remaining in the Bluetooth GPS device. |
A value between 0-100 (100 means battery is full) |
|
The battery charge remaining in the Bluetooth GPS device represented in three different bands: |
Defined by TBTGPSBatteryState. |
|
Whether an external antenna is connected to Bluetooth GPS device. An external antenna can be connected to a GPS device when it is in an environment where the GPS signal is weak or blocked. |
Defined by TBTGPSExtAntennaState. |
|
Whether a battery charger is connected to the Bluetooth GPS device. |
Defined by TBTGPSExtPowerState. |
|
Version of Bluetooth GPS PSY currently in use. |
Descriptor with maximum length 32. |
|
Version of Bluetooth hardware in the Bluetooth GPS device. |
Descriptor with maximum length 32.
|
|
Version of Bluetooth software in the Bluetooth GPS device. |
Descriptor with maximum length 32. |
|
Version of GPS chipset in the Bluetooth GPS device. |
Descriptor with maximum length 32. |
|
Version of GPS software in the Bluetooth GPS device. |
Descriptor with maximum length 32. |
Listening for changes in the state of Bluetooth GPS PSY
Figure 1 is a sequence diagram describing notifications to the client about Bluetooth GPS PSY state changes.
Retrieving current state of Bluetooth GPS PSY
Figure 2 shows a sequence diagram that describes retrieval of the current state of Bluetooth GPS PSY.
The Bluetooth GPS PSY Events API does not define or use any error codes. Refer to the RProperty class description in reference documentation for further details on error handling when using Publish and Subscribe.
The Bluetooth GPS PSY Events API does not require any additional memory above that needed for normal use of Publish and Subscribe.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.