How to use module selection criteria

This document describes how to specify module selection criteria as part of a location request.

Positioning technology module selection criteria describes module selection criteria.

A client application specifies module selection criteria in order to influence the choice of positioning technology module made by the location server.

This following code demonstrates how a client application gets location information using module selection criteria.

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

...

RPositionServer server;
RPositioner positioner;

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

// 2. Define module selection criteria
TPositionCriteria criteria;
TPositionQuality quality;
TPositionSelectionOrder order;

// Set required capabilities - want altitude information...
criteria.AddRequiredCapabilities(TPositionModuleInfo::ECapabilityVertical);

// Set quality - want vertical position within 100m
User::LeaveIfError(quality.SetVerticalAccuracy(100));

// Set ordering - make vertical accuracy a high priority
User::LeaveIfError(order.SetOrderVerticalAccuracy(TPositionSelectionOrder::EOrderHigh));

criteria.setRequiredQuality(quality);
criteria.SetSelectionOrder(order);

User::LeaveIfError(positioner.Open(server, criteria));
CleanupClosePushL(positioner);

// 3. Request location information
TPositionInfo posInfo;
TPosition pos;
TRequestStatus status;

// Wait for response...
positioner.NotifyPositionUpdate(posInfo, status);
User::WaitForRequest(status);

// 4. Receive and use the location information
if (status != KErrNone)
 {
  // Handle possible errors
  ...
 }

// Get the position data object from the wrapper info object
pos = posInfo.GetPosition(pos);


// 5. Close the subsession and session
CleanupStack::PopAndDestroy(&positioner);
CleanupStack::PopAndDestroy(&server);

The following sections describe the steps shown in the above code example.

1. Create a session with the Location Server

To create a session with the Location Server, a client application:

• Creates an instance of RPositionServer

• Calls RPositionServer::Connect()

Standard client-server error codes are returned by calls to open the session. Error and panic codes specific to LBS are defined in LbsErrors.h.

2. Define the module selection criteria and create a subsession

The client application:

1. Creates a module selection criteria object of class TPositionCriteria on which the module's required capabilities are set by calling TPositionCriteria::AddRequiredCapabilities().

2. Creates a quality of position object of class TPositionQuality and defines the required quality of position.

3. Creates an ordering object of class TPositionSelectionOrder on which it sets the relative importance of the various position quality parameters.

4. Calls TPositionCriteria::SetQuality() and TPositionCriteria::SetSelectionOrder() on the criteria object to set the required position quality and the relative importance of the quality parameters.

5. Calls RPositioner::Open(), passing the criteria object as a parameter. The location framework selects the best module based on the supplied criteria.

3. Request the location information

The application calls RPositioner::NotifyPositionUpdate() with a TRequestStatus object.

4. Receive location information

The TRequestStatus object is updated when the location server has calculated the device location.

5. Close the server subsession and session

If the server subsession and session are no longer required then they are closed by calling RPositioner::Close() and RPositionServer::Close(). In the code example the cleanup stack function is used.

Positioning technology module selection criteria