1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <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;

    13 #include <LbsErrors.h>

    14 

    15 ...

    16 

    17 RPositionServer server;

    18 

    19 TPositionModuleId modId;

    20 TPositionModuleStatus modStatus;

    21 

    22 // Create a session with the Location Server

    23 User::LeaveIfError(server.Connect());

    24 CleanupClosePushL(server);

    25 

    26 //    Assume that the app has the Id of the module for which it wants status

    27 // Set modId (details omitted)

    28  ...

    29 

    30 // Get module status

    31 User::LeaveIfError(server.GetModuleStatus(modStatus, modId));

    32 

    33 // Use the status

    34 TPositionModuleStatus::TDeviceStatus deviceStatus = modStatus.DeviceStatus();

    35 TPositionModuleStatus::TDataQualityStatus qualityStatus = modStatus.DataQualityStatus();

    36 

    37 // Can check the status of the module device - for example check for device error

    38 if (deviceStatus == TPositionModuleStatus::EDeviceError) 

    39  {

    40  // Device error for this module

    41     ...

    42  }

    43 

    44 // Can check the data quality for the module - for example check for loss of data quality

    45 if (qualityStatus == TPositionModuleStatus::EDataQualityLoss)

    46  {

    47  // Loss of quality for this module

    48  ...

    49  }

    50 

    51 // Close the server session

    52 CleanupStack::PopAndDestroy(&server);

    53 

    54 

    55 </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;

    56 #include <LbsErrors.h>

    57 

    58 ...

    59 

    60 RPositionServer server;

    61 TPositionModuleStatus modStatus;

    62 TPositionModuleStatusEvent modEvents;

    63 

    64 // Create a session with the Location Server

    65 User::LeaveIfError(server.Connect());

    66 CleanupClosePushL(server);

    67 

    68 // 1. Define the types of status events for which notification is required

    69 TPositionModuleStatusEventBase::TModuleEvent requestedEvents =

    70 TPositionModuleStatusEventBase::EEventDeviceStatus | 

    71 TPositionModuleStatusEventBase::EEventDataQualityStatus;

    72 

    73 modEvents.setRequestedEvents(requestedEvents);

    74           

    75 //    2. Request module status change notifications for all modules

    76 TRequestStatus status;

    77 

    78 server.NotifyModuleStatusEvent(modEvents, status);

    79 

    80 // Wait (maybe a very long time!) for an event to occur. This is just for example

    81 // Would use an active object in production code

    82 

    83 User::WaitForRequest(status);

    84 

    85 

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

    87 

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

    89 

    90 

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

    92 

    93 modEvents.GetModuleStatus(modStatus);

    94 

    95 TPositionModuleStatus::TDeviceStatus deviceStatus = modStatus.DeviceStatus();

    96 TPositionModuleStatus::TDataQualityStatus qualityStatus = modStatus.DataQualityStatus();

    97 

    98 

    99 if (deviceStatus == TPositionModuleStatus::EDeviceError) 

   100     {

   101         // Device error for this module

   102         ...

   103     }

   104 

   105 // Can check the data quality for the module

   106 if (qualityStatus == TPositionModuleStatus::EDataQualityLoss)

   107     {

   108         // Loss of quality for this module

   109         ...

   110     }

   111 

   112 // Close the server session

   113 CleanupStack::PopAndDestroy(&server);

   114 

   115 

   116 </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

   117           RPositionServer::NotifyModuleStatusEvent(TPositionModuleStatusEventBase&

   118           aStatusEvent, TRequestStatus& aStatus, const TPositionModuleId aModuleId =

   119           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>