Collapse all Symbian^3 Product Developer Library

Positioning Indicator API

The Positioning Indicator API defines P&S keys for publishing and subscribing for the current status of positioning hardware in the mobile device. The API is deprecated.

It was intended for use by UI components (such as the UI status bar) that require updates of that status of positioning hardware. The Integrated GPS Hardware Status API now contains an observer class that allows UI components to receive hardware status updates.

Purpose

This document describes the Positioning Indicator API. It defines Publish and Subscribe (P&S) keys for properties for notifying of changes to GPS hardware status.

The API is deprecated. It was intended for use by UI components. The Integrated GPS Hardware Status API is the recommended way of updating UI components with the GPS hardware status.

API description

The API can be used to update UI components when the status of GPS hardware changes.

API summary

The API defines no classes. It defines only global constants which are the Positioning UI Indicator P&S category (KPosIndicatorCategory) and key (KPosIntGpsHwStatus) and an enumeration TPosIntGpsHwState that defines the values that the P&S property can take.

The definitions are in locationfwdomainpsKey.h are summarised in table 1.

Constant Name	Description
KPosIndicatorCategory	The UID of Positioning Indicator P&S keys category.
KPosIntGpsHwStatus	The ID of the Integrated GPS HW status key. It contain values defined by TPosIntGpsHwIndicatorState. The default value (i.e. when this key is not found) is EPosIntGpsHwIndicatorOff. If it contains any value other than one defined in TPosIntGpsHwState, the value must be ignored and TPosIndicatorState::EPosIntGpsHwIndicatorOff must be assumed.

Constant Name

Description

KPosIndicatorCategory

The UID of Positioning Indicator P&S keys category.

KPosIntGpsHwStatus

The ID of the Integrated GPS HW status key. It contain values defined by TPosIntGpsHwIndicatorState.

The default value (i.e. when this key is not found) is EPosIntGpsHwIndicatorOff.

If it contains any value other than one defined in TPosIntGpsHwState, the value must be ignored and TPosIndicatorState::EPosIntGpsHwIndicatorOff must be assumed.

Table 1. Positioning IndicatorP&S category and key definitions.

Libraries

The P&S keys of the Positioning Indicator API are defined in locationfwdomainpsKey.h. This API uses the Publish and Subscribe API and there are no additional libraries required by a client.

Capabilities

An API client does not require any capabilities to read the property value.

Using the API

This API supports only one typical use case:

Updating the state of a positioning UI indicator

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 & Subscribe API (see RProperty for details).

The client subscribes for changes in KPosIntGpsHwStatus P&S key from KPosIndicatorCategory category. When a state change is reported, a client reads the new value and update UI indicator accordingly.

The TPosIntGpsHwState enumeration defines the possible values of the KPosIntGpsHwStatus property. If any other value is retrieved it must be ignored and the value TPosIndicatorState::EPosIntGpsHwIndicatorOff assumed. If the key is not found, then EPosIntGpsHwIndicatorOff must be assumed as its value.

Figure 1 shows how a client reads and updates UI indicator based on the states of Positioning Indicator P&S key.

Figure 1. Figure 1. Updating the state of Positioning UI Indicator sequence diagram

Refer to RProperty class description in the Symbian platform Reference and "Publish and Subscribe" article in Symbian Guide for further details on using P&S keys.

The following table describes the mapping of KPosIntGpsHwStatus key values and status of the UI indicator that should be set:

Key value	Indicator state	Comment
`TPosIndicatorState::EPosIntGpsHwOff`	Hidden	GPS hardware is OFF and indicator should be hidden.
`TPosIndicatorState::EPosIntGpsHwOn`	Shown	GPS hardware is ON and indicator should be shown.
`TPosIndicatorState::EPosIntGpsHwIntermediate`	Animated	GPS hardware in intermediate state. UI indicator is shown in intermediate (possibly animated) state.

Error handling

This API does not define or use any error codes.

Refer to RProperty class description in the Symbian platform Reference for further details on error handling in Publish & Subscribe API.