<?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-F5944819-2942-5ADA-A0AD-510D20BFBDEB"><title>How to get module status changes</title><shortdesc>This document demonstrates how a client application uses the API to get device status and quality status events from positioning modules. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>This document describes how a client application gets a positioning module's current status and notification of module status changes. </p> </section> <section><title>Required background</title> <p> <xref href="GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita">Positioning technology module status</xref> describes module status. </p> </section> <section><title>Getting the current status of a module</title> <p>The following code is a simple example of how a client application would get a module's current status. </p> <codeblock id="GUID-AF53F14E-FBDF-5804-A169-51B36182F32B" xml:space="preserve">#include &lt;lbs.h&gt;
#include &lt;LbsErrors.h&gt;

...

RPositionServer server;

TPositionModuleId modId;
TPositionModuleStatus modStatus;

// Create a session with the Location Server
User::LeaveIfError(server.Connect());
CleanupClosePushL(server);

//    Assume that the app has the Id of the module for which it wants status
// Set modId (details omitted)
 ...

// Get module status
User::LeaveIfError(server.GetModuleStatus(modStatus, modId));

// Use the status
TPositionModuleStatus::TDeviceStatus deviceStatus = modStatus.DeviceStatus();
TPositionModuleStatus::TDataQualityStatus qualityStatus = modStatus.DataQualityStatus();

// Can check the status of the module device - for example check for device error
if (deviceStatus == TPositionModuleStatus::EDeviceError) 
 {
 // Device error for this module
    ...
 }

// Can check the data quality for the module - for example check for loss of data quality
if (qualityStatus == TPositionModuleStatus::EDataQualityLoss)
 {
 // Loss of quality for this module
 ...
 }

// Close the server session
CleanupStack::PopAndDestroy(&amp;server);


</codeblock> <p>A client application must know the unique ID of the module for which it wants the current status. </p> <p>See <xref href="GUID-A4B47A7A-17EB-570C-AD88-6756B34AF634.dita">How to use module information</xref> for information about how to get module information, including the ID. </p> <p>The application calls <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> to get the module status at that point in time. Module status can change and there is no guarantee as to how long the returned status will remain valid. To be notified when a module status changes, an application must request status change notifications (see below). </p> </section> <section id="GUID-33296811-45B4-5B45-9726-6CDAF46477B1"><title>Getting module status change notifications</title> <p>A client application can receive notification of device status change events, quality status change events and system events. </p> <p>In the code example below, the application waits on a module status change which may not occur for some time, if ever. A production application would use more sophisticated event notification with an active object. </p> <codeblock id="GUID-D1B3D745-6FCA-5CD6-814B-652AB7000332" xml:space="preserve">#include &lt;lbs.h&gt;
#include &lt;LbsErrors.h&gt;

...

RPositionServer server;
TPositionModuleStatus modStatus;
TPositionModuleStatusEvent modEvents;

// Create a session with the Location Server
User::LeaveIfError(server.Connect());
CleanupClosePushL(server);

// 1. Define the types of status events for which notification is required
TPositionModuleStatusEventBase::TModuleEvent requestedEvents =
TPositionModuleStatusEventBase::EEventDeviceStatus | 
TPositionModuleStatusEventBase::EEventDataQualityStatus;

modEvents.setRequestedEvents(requestedEvents);
          
//    2. Request module status change notifications for all modules
TRequestStatus status;

server.NotifyModuleStatusEvent(modEvents, status);

// Wait (maybe a very long time!) for an event to occur. This is just for example
// Would use an active object in production code

User::WaitForRequest(status);


// 3. Check the types of status changes that have occurred

TPositionModuleStatusEventBase::TModuleEvent occurredEvents = modEvents.OccurredEvents();


// Check the type of event that occurred...

modEvents.GetModuleStatus(modStatus);

TPositionModuleStatus::TDeviceStatus deviceStatus = modStatus.DeviceStatus();
TPositionModuleStatus::TDataQualityStatus qualityStatus = modStatus.DataQualityStatus();


if (deviceStatus == TPositionModuleStatus::EDeviceError) 
    {
        // Device error for this module
        ...
    }

// Can check the data quality for the module
if (qualityStatus == TPositionModuleStatus::EDataQualityLoss)
    {
        // Loss of quality for this module
        ...
    }

// Close the server session
CleanupStack::PopAndDestroy(&amp;server);


</codeblock> <p>The following sections describe the steps to get module status change notifications as shown in the code example above. </p> <p><b>1. Define the types of module status events for which notification is required </b> </p> <p>The client application creates a <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> object with 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> variable which defines the status events in which it is interested. </p> <p><b>2. Request module status change notifications </b> </p> <p>The client application calls the method <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 make a request for module status change notifications. The full signature of this method is: </p> <p> <codeph>void
          RPositionServer::NotifyModuleStatusEvent(TPositionModuleStatusEventBase&amp;
          aStatusEvent, TRequestStatus&amp; aStatus, const TPositionModuleId aModuleId =
          KPositionNullModuleId) const</codeph>  </p> <p>If the <xref href="GUID-1104624D-88F7-36EE-9C9D-470346C10318.dita"><apiname>TPositionModuleId</apiname></xref> parameter is passed, then the application is notified of status changes for that module only. If the parameter is not passed then the application is notified of status changes for all modules. </p> <p>On completion, the <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> value is updated and the <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita"><apiname>TPositionModuleStatusEvent</apiname></xref> object now also holds details of the types of events that have occurred. </p> <p><b>3. Check the types of status changes that have occurred </b> </p> <p>The <xref href="GUID-F1E97CB3-BFBF-34E9-8ED8-192FA99766BF.dita"><apiname>TModuleStatusEvent</apiname></xref> object contains both the requested event types and the event types that occurred. </p> <p>The requested event types are accessed by calling <xref href="GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA.dita#GUID-6E827E6E-69EF-3EA3-95FF-9A0B38B689EA/GUID-69CEFEA8-1BC3-3010-81CB-63D4B4DC05C9"><apiname>TPositionModuleStatusEvent::RequestedEvents()</apiname></xref>. </p> <p>The event types that occurred are accessed by calling <xref href="GUID-F1E97CB3-BFBF-34E9-8ED8-192FA99766BF.dita#GUID-F1E97CB3-BFBF-34E9-8ED8-192FA99766BF/GUID-68D84535-F833-3F53-927B-D03DA4532E77"><apiname>TModuleStatusEvent::OccurredEvents()</apiname></xref>. </p> <p>Both of these methods return bit mask values of type <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>. </p> <p>Partial updates can occur. For example an application can request notification of both device status and quality status changes and it will receive notification when either one of these occurs. Therefore it may be necessary for an application to check the types of the occurred events. </p> <p> <b>Notes</b>  </p> <p>To obtain further updates when a call to <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> completes, it is necessary to re-issue the request by calling this method again. </p> <p>A client application can only have one outstanding request for module status updates per server session. An attempt to make a second request for location information while one is still outstanding causes a panic. An application must cancel an outstanding request before it makes another request. </p> <p>To cancel an outstanding request for module status updates, an application calls <xref href="GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B.dita#GUID-0ADC4654-7F7B-3B53-A2F9-7035670F501B/GUID-FF06E754-B7AB-30CB-A456-445F283FDB28"><apiname>RPositionServer::CancelRequest()</apiname></xref> and passes <xref href="GUID-32B5A1A4-ADB6-33B9-A104-E3D3AF1884F1.dita"><apiname>EPositionServerNotifyModuleStatusEvent</apiname></xref> as a parameter. </p> </section> </conbody></concept>