<?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-AC7069ED-8CA5-55FC-9DF6-595C0505C672"><title>Positioning Module Status</title><shortdesc>This document describes positioning technology module status, which applications access through the Location Acquisition API. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This document describes Positioning Module status, which applications access through the Location Acquisition API. </p> </section> <section><title>Positioning Module status</title> <p>A Positioning Module has a <i>status</i> which is represented by a <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita"><apiname>TPositionModuleStatus</apiname></xref> object. The status describes the low-level state of a Positioning Module, such as whether it is disabled, initialising, or ready to retrieve location data, as well as its data quality status. </p> <p>A change in Positioning Module status is indicated by a <i>status event</i>. Details of the event are held in a <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> object. Client applications can receive notification of status events from the location server. </p> <p>Figure 1 illustrates Positioning Module status and event classes. </p> <fig id="GUID-C17083CB-4252-547F-BAAC-4388A105FEC1"><title>

             Figure 1. TPositionModuleStatus and

             TPositionModuleStatusEvent classes 

          </title> <image href="GUID-7D13B61C-0C9E-5098-87F0-BB9D741E9281_d0e272018_href.png" placement="inline"/></fig> <p><b>TPositionModuleStatus </b> </p> <p> <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita"><apiname>TPositionModuleStatus</apiname></xref> describes the status of a Positioning Module. An application gets information about a Positioning Module's current status by calling <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-676FAC1B-1989-3D3C-84A5-DF82B874D7A3"><apiname>RPositionServer::GetModuleStatus()</apiname></xref>. There are two status types - <i>device status</i> and <i>data quality status</i>. </p> <p><b>Device status </b> </p> <p>Device status is the status of the hardware device utilised by a Positioning Module, such as the chipset used by an A-GPS Positioning Module. </p> <p> <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita#GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039/GUID-3702B7D3-EDE5-3FD9-B0D5-96C5FD4B32E6"><apiname>TPositionModuleStatus::DeviceStatus()</apiname></xref> returns the device status as a <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita#GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039/GUID-4C1E0860-4813-3B3F-A766-9F759ADC9E7C"><apiname>TPositionModuleStatus::TDeviceStatus</apiname></xref> value. The value returned can indicate a transient device status, such as whether the hardware is disabled, initialising, or ready. It can also indicate a more serious device error state. </p> <p><b>Data quality status </b> </p> <p>Data quality status describes the accuracy of the location data that a Positioning Module is able to provide at a point in time. </p> <p> <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita#GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039/GUID-FE9B37E2-7302-3818-A5F1-95669500FB14"><apiname>TPositionModuleStatus::DataQualityStatus()</apiname></xref> returns the data quality status as a <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita#GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039/GUID-08F4C71A-86B1-3B4C-A6C4-E181E218C533"><apiname>TPositionModuleStatus::TDataQualityStatus</apiname></xref> value. This value indicates whether the quality of location data is normal (the ideal condition), partially degraded or completely degraded. Location data quality can become degraded because the mobile device has moved out of range of any base stations or is in a position where it cannot receive signals from positioning satellites. Note that loss of information quality does not indicate a device error, which would be flagged by a change in the device status. </p> </section> <section><title>Positioning Module status events</title> <p>When a Positioning Module's status changes, a Positioning Module status event occurs. </p> <p>There are three types of Positioning Module status events: </p> <ul><li id="GUID-0852F3C8-9301-53E8-8769-74387D8499F1"><p>Device status events </p> </li> <li id="GUID-21995DC6-54A5-5585-85D2-0B09E7008533"><p>Data quality status events </p> </li> <li id="GUID-66A5D75B-9E5D-588A-872D-CBF2D818A6DF"><p>System level events. These events indicate that a Positioning Module has been added or removed in the system. </p> </li> </ul> <p><b>TPositionModuleStatusEvent </b> </p> <p>An object of class <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> has two functions: </p> <ul><li id="GUID-3389C877-68DE-505E-BB83-F8977D0E1C6D"><p>As the object on which an application defines the types of Positioning Module status events for which it requests notification. These are set by calling <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita#GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA/GUID-132DB32E-6A60-3CEC-9445-146B82E6D9CC"><apiname>TPositionModuleStatusEvent::SetRequestedEvents()</apiname></xref> passing a <xref href="GUID-33ED1FC9-3B34-3AB5-A924-C361C712BD1B.dita#GUID-33ED1FC9-3B34-3AB5-A924-C361C712BD1B/GUID-65DC3D52-46D8-33C9-BC70-6289022419A1"><apiname>TPositionModuleStatusEventBase::TModuleEvent</apiname></xref> bitmask value as a parameter to define the combination of events </p> </li> <li id="GUID-4E812AE8-5342-58DA-9690-EFA7E575DA46"><p>As the object on which the location framework sets the type of events that have occurred. These are retrieved by calling <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita#GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA/GUID-56695C9E-B488-3F9A-ADB6-04BB33433BF3"><apiname>TPositionModuleStatusEvent::OccurredEvents()</apiname></xref> and checking the returned <xref href="GUID-33ED1FC9-3B34-3AB5-A924-C361C712BD1B.dita#GUID-33ED1FC9-3B34-3AB5-A924-C361C712BD1B/GUID-65DC3D52-46D8-33C9-BC70-6289022419A1"><apiname>TPositionModuleStatusEventBase::TModuleEvent</apiname></xref> value. </p> </li> </ul> <p><b>Event notification </b> </p> <p>An application calls <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-3AA81126-EB13-3F1B-9464-E86CC7769EB5"><apiname>RPositionServer::NotifyModuleStatusEvent()</apiname></xref> to receive notification of Positioning Module status changes, passing a reference to a <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> object on which it has set the requested events. An application also supplies a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object and optionally a <xref href="GUID-1104624D-88F7-36EE-9C9D-470346C10318.dita"><apiname>TPositionModuleId</apiname></xref> object if status changes from only one Positioning Module are required. </p> <p>When the status of a Positioning Module changes, the client application is notified. The <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> <codeph/> object that was supplied to the location server now also contains details of the events that have occurred and these are obtained by calling <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita#GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA/GUID-56695C9E-B488-3F9A-ADB6-04BB33433BF3"><apiname>TPositionModuleStatusEvent::OccurredEvents()</apiname></xref>. </p> <p>The Positioning Module status is obtained by calling <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita#GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA/GUID-7707E844-34A2-3454-88C9-0456382ACD40"><apiname>TPositionModuleStatusEvent::GetModuleStatus()</apiname></xref> providing a <xref href="GUID-F8376F62-46F2-3E7C-9536-920DB6FC6039.dita"><apiname>TPositionModuleStatus</apiname></xref> reference as a parameter. </p> <p>See <xref href="GUID-F5944819-2942-5ADA-A0AD-510D20BFBDEB.dita">How to Get Positioning Module Status Changes</xref> for an example. </p> </section> <section><title>Uses of Positioning Module status</title> <p>Quality status events are useful for applications that need to modify their behaviour based on the quality of location information that can be received. For example, an application may need to show a message when a user moves into an area where the accuracy of location information is degraded to a lower quality than is required because of distance from a base station or inability to receive satellite signals. </p> <p>Device status events and system Positioning Module events are most useful to software components that perform administrative operations, such as taking a Positioning Module online or offline. The events can be used to notify when such an administrative operation is complete. </p> <p>Device status events can also be used to keep a user informed as to the status of a particular Positioning Module. For example, a phone status bar could be updated to show that GPS is active when location information is being received. </p> </section> <section><title>See also</title> <p><xref href="GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita">Positioning Modules</xref>  </p> </section> </conbody></concept>