How to use module information

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

Positioning technology modules describes module concepts.

Client applications use the RPositionServer class to get information about the positioning technology modules available to the location server. Applications may want this information in order to choose a particular module to use for location information requests.

The following code is a simple example of how a client application can get 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 module information:

1. Create a session with the location server

A client application creates a session with the location server from which 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 modules installed

The number of installed positioning technology modules is known to the location server and is available to client applications by calling RPositionServer::GetNumModules().

3. Iterate over the modules to get information about each module

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

4. Get the availability of a module

TPositionModuleInfo::IsAvailable() returns the availability of a module. If this method returns EFalse then the 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 module back online in a control panel.

Note

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

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

TPositionModuleInfo::TechnologyType() returns information about the type of technology used by the positioning module.

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

TPositionModuleInfo::GetPositionQuality() returns a TPositionQuality object that describes the quality of position that the 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.

A client application calls RPositionServer::GetModuleById() to get information about a module when the module ID is known.

TPositionModuleInfo modInfo;

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

Positioning technology modules