How to Use Positioning Module Information

Purpose

This section describes how a client application gets Positioning Module information using the Location Acquisition API and how this information can be used in a request for location information.

Required background

Positioning Modules describes module concepts.

How to get information about all Positioning Modules

Client applications use the RPositionServer class to get information about the Positioning Modules available to the Location Server. Applications may want this information in order to choose a particular Positioning Module to use for location information requests.

The following code is a simple example of how a client application can get Positioning Module information. The client specifies use of assisted GPS and accuracy better than 10 metres.

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

RPositionServer server;

TUint numModules;
TPositionModuleId modId;
TPositionModuleInfo modInfo;
TPositionModuleStatus modStatus;

TBool foundModule = EFalse;


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

// 2. Get the number of modules installed
User::LeaveIfError(server.GetNumModules(numModules));

// 3. Iterate over the modules to get information about each module
// 4. Get the availability of a module
// 5. Get information about the module technology, quality etc.

for (TUint I=0 ; I < numModules ; I++)
 {
 User::LeaveIfError(server.GetModuleInfoByIndex(I, modInfo));
        
 /* Check module technology type and availability 
    In this example - does the module support assisted capability
    and is the module available? */
 
 if ( modInfo.IsAvailable() && (modInfo.TechnologyType() == ETechnologyAssisted) )
  {

  /* Check module capabilities
        In this example does the module supply speed information? */

  TCapabilities caps = modInfo.Capabilities();
  if (caps & ECapabilitySpeed) 
   { 
   // Check module position quality
   TPositionQuality quality;
   modInfo.GetPositionQuality(quality);
                                    
   // In this example, check for horizontal accuracy better than 10 metres
   if ( !quality.HorizontalAccuracy().IsNaN() && quality.HorizontalAccuracy() < 10 )
    {
    // This module has all the required characteristics!
    modId = modInfo.ModuleId();
    foundModule = ETrue;
    break; // stop searching
    }
   }    
  }
 }

if (foundModule)
 {
 // Can use the module to get location information
 ...
 }
else 
 {
    // No module meets these requirements. Look for another?
    ...
 }

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

The following sections describe the steps to get Positioning Module information:

1. Create a session with the Location Server

A client application creates a session with the Location Server from which Positioning Module information is obtained. Note that if a server session has been created already (for example to get location information) then the application must use it. If the application attempts to open a second session with the server a panic will occur.

2. Get the number of Positioning Modules installed

The number of installed Positioning Modules is known to the Location Server and is available to client applications by calling RPositionServer::GetNumModules().

3. Iterate over the Positioning Modules to get information about each one

Once a client application knows the number of Positioning Modules, it can easily iterate over them to get information for each one by calling RPositionServer::GetModuleInfoByIndex().

4. Get the availability of a Positioning Module

TPositionModuleInfo::IsAvailable() returns the availability of a Positioning Module. If this method returns EFalse then the Positioning Module cannot be used. It may have been taken offline or there may be a device hardware problem. The availability will not change unless there is some kind of user intervention, such as bringing the unavailable Positioning Module back online in a control panel.

Note

A Positioning Module also has a status that can change over time. Module status provides more detailed information about a Positioning Module's state than a simple availability flag. Module status information is held in a TPositionModuleStatus object. A Positioning Module's status at a point in time is discovered by calling RPositionServer::GetModuleStatus().

5. Get information about the Positioning Module technology, capabilities and position quality

TPositionModuleInfo::TechnologyType() returns information about the type of technology used by the Positioning Module.

TPositionModuleInfo::Capabilities() returns a Positioning Module's capabilities as a bit mask.

TPositionModuleInfo::GetPositionQuality() returns a TPositionQuality object that describes the quality of position that the Positioning Module can provide.

6. Close the server session

If the server session is not needed for any further processing then the application must close it.

How to get information about a specific Positioning Module

A client application calls RPositionServer::GetModuleById() to get information about a Positioning Module when its ID is known.

TPositionModuleInfo modInfo;

// modId is known to the client application
User::LeaveIfError(server.GetModuleInfoById(modId, modInfo));
...