How to get module status changes

Purpose

This document describes how a client application gets a positioning module's current status and notification of module status changes.

Required background

Positioning technology module status describes module status.

Getting the current status of a module

The following code is a simple example of how a client application would get a module's current status.

#include <lbs.h>
#include <LbsErrors.h>

...

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(&server);

A client application must know the unique ID of the module for which it wants the current status.

See How to use module information for information about how to get module information, including the ID.

The application calls RPositionServer::GetModuleStatus() 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).

Getting module status change notifications

A client application can receive notification of device status change events, quality status change events and system events.

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.

#include <lbs.h>
#include <LbsErrors.h>

...

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(&server);

The following sections describe the steps to get module status change notifications as shown in the code example above.

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

The client application creates a TPositionModuleStatusEvent object with a TPositionModuleStatusEventBase::TModuleEvent variable which defines the status events in which it is interested.

2. Request module status change notifications

The client application calls the method RPositionServer::NotifyModuleStatusEvent() to make a request for module status change notifications. The full signature of this method is:

void RPositionServer::NotifyModuleStatusEvent(TPositionModuleStatusEventBase& aStatusEvent, TRequestStatus& aStatus, const TPositionModuleId aModuleId = KPositionNullModuleId) const

If the TPositionModuleId 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.

On completion, the TRequestStatus value is updated and the TPositionModuleStatusEvent object now also holds details of the types of events that have occurred.

3. Check the types of status changes that have occurred

The TModuleStatusEvent object contains both the requested event types and the event types that occurred.

The requested event types are accessed by calling TPositionModuleStatusEvent::RequestedEvents().

The event types that occurred are accessed by calling TModuleStatusEvent::OccurredEvents().

Both of these methods return bit mask values of type TPositionModuleStatusEventBase::TModuleEvent.

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.

Notes

To obtain further updates when a call to RPositionServer::NotifyModuleStatusEvent() completes, it is necessary to re-issue the request by calling this method again.

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.

To cancel an outstanding request for module status updates, an application calls RPositionServer::CancelRequest() and passes EPositionServerNotifyModuleStatusEvent as a parameter.