Symbian^3 Product Developer Library > Symbian Guide > Location Based Services (LBS) Guide > Location Management > Location Admin > A-GPS Location Data Source API >

A-GPS Location Data Source API

This document describes the A-GPS Location Data Source API that device creators use to integrate with A-GPS hardware.

Purpose

This document describes the A-GPS (Assisted GPS) Location Data Source API that a licensee's GPS/A-GPS Integration Module must implement to integrate GPS hardware with the LBS subsystem. It is intended to give licensee Integration Module writers an understanding of the API, how it is called by the LBS subsystem and the behaviour expected from Integration Modules.

This document contains links to A-GPS Location Data Source API reference documentation that can be followed to obtain full descriptions of API classes and methods.

Contents

Introduction

Licensees who want to use GPS technology in their phones must integrate the GPS hardware with the LBS subsystem. To do this they must create a GPS or A-GPS (Assisted GPS) Integration Module. An Integration Module provides the adaptation layer between the LBS subsystem and the GPS hardware. It is an ECOM plug-in that is loaded by the LBS subsystem A-GPS Location Manager on start-up.

This document describes the A-GPS Location Data Source API. The API defines the interface between the LBS subsystem and an Integration Module. Symbian provides a reference implementation of an A-GPS Integration Module based on a SiRF chipset. Licensees can use the Symbian reference implementation as the basis of their own A-GPS Integration Module (see A-GPS reference module overview for more information).

For a high-level description of LBS architecture, see LBS architecture overview. For a more detailed explanation of the architecture see SGL.TS0004.202 LBS Architectural Description (in the LBS source distribution documentation folder).

GPS modes

Different GPS hardware chipsets may support different GPS capabilities: hardware may produce GPS position fixes (latitude, longitude and altitude data) or, more simply, GPS measurements that must be used by software outside of the GPS hardware to calculate a position fix.

The four GPS modes supported by the LBS subsystem are:

  • Autonomous mode

    In autonomous mode GPS hardware calculates a position fix without using assistance data from the network. This typically takes longer than if assistance data were used to calculate the fix.

  • Terminal based mode (TB)

    In terminal based mode the Integration Module and GPS hardware use assistance data received from the network to calculate a GPS position fix and return it to the LBS subsystem.

  • Terminal assisted mode (TA)

    In terminal assisted mode, the GPS hardware produces GPS measurements (with the help of assistance data from the network).

    In the Symbian LBS subsystem the Integration Module returns the GPS measurements which are sent to a network-based server. The measurements are used to calculate a position fix.

  • Simultaneous support of TB + TA modes

    GPS hardware may be able to return both GPS measurements and position fixes. An Integration Module can return the GPS measurements as they are received from GPS satellites together with GPS position fixes that are increasingly complete and/or accurate.

    As in TA mode, the LBS subsystem returns the GPS measurements to the network for calculation. Either the network of the Integration Module may be the first to return a position of the required accuracy (as specified by a client process).

Licensees can implement their Integration Modules to support more than one GPS mode. A module may support terminal based mode with the ability to fallback to autonomous mode if assistance data is not available. A module may also be designed to support either TB or TA, but not TB + TA.

An Integration Module publishes the GPS mode it supports in a configuration file. LBS uses the configuration file, the LBS subsystem administration settings and any preferences received from the network to set the GPS mode that an Integration Module uses to calculate a position fix. Later sections of this document describe how LBS sets an Integration Module's GPS mode.

A-GPS Location Data Source API description

This section describes the classes of the A-GPS Location Data Source API.

A-GPS Location Data Source API class diagram

Figure 1 shows the classes of the A-GPS Location Data Source API.

The main classes of the API are CLbsLocationSourceGpsBase and MLbsLocationSourceGpsObserver which together model an observer/observable design pattern. A licensee's Integration Module must derive from CLbsLocationSourceGpsBase. The LBS subsystem (A-GPS Location Manager) implements MLbsLocationSourceGpsObserver.

Note: All of the methods of the CLbsLocationSourceGpsBase are synchronous and their implementations in a licensee Integration Module must return quickly.

Figure 1. Figure 1. A-GPS Location Data Source API classes

API classes and types

Table 1 lists the classes and types that define the A-GPS Location Data Source API. Further details about the classes can be found by following the links to reference documentation.

The A-GPS Location Data Source API has publishedPartner interface access.

Class/type name Description Header file

CLbsLocationSourceGpsBase

The base class for all A-GPS Integration Module implementations. It defines the methods that the LBS subsystem uses to request GPS measurements or a GPS position fix, to set the mode of operation of the GPS hardware and to send power advice.

LbsLocDataSourceGpsBase.h

MLbsLocationSourceGpsObserver

The GPS Integration Module observer class implemented by the LBS subsystem (A-GPS Location Manager). It defines the methods that an A-GPS module uses to request assistance data, return GPS measurements or a position fix, and send module status messages into LBS.

LbsLocDataSourceGpsBase.h

CLbsLocationSourceGpsBase::TPowerMode

Defines a set of values for power advice. A value is a parameter in CLbsLocationSourceGpsBase::AdvisePowerMode().

LbsLocDataSourceGpsBase.h

TLbsLocRequestQuality

Specifies the desired quality of a location request. TLbsLocRequestQuality is used to specify the desired quality of a location request to an Integration Module. A reference to an object of this type is passed to CLbsLocationSourceBase::UpdateLocation().

LbsLocDataSourceGpsBase.h

TLbsGpsOptions

This is the default class used to hold various global settings for the GPS integration module including the GPS positioning mode required. It has the method TLbsGpsOptions::SetGpsMode() that is used to set the GPS positioning mode of the module (such as terminal based or terminal assisted mode).

LbsLocDataSourceGpsBase.h

TLbsGpsOptionsItem (from v9.3)

An item in a TLbsGpsOptionsArray. The item specifies the type of update required from a module - a position fix or a set of GPS measurements or both.

LbsLocDataSourceGpsBase.h

TLbsGpsOptionsArray (from v9.3)

This class is derived from TLbsGpsOptions. It is only passed as a parameter in CLbsLocationSourceGpsBase::UpdateLocation() when the network has asked the LBS subsystem to work in TB + TA mode. For more information see LBS sets GPS options.

LbsLocDataSourceGpsBase.h

Table 1 Classes and types of the A-GPS Location Data Source API.

Table 2 lists the assistance data classes and types that are passed across the API. The classes and types are used to specify the assistance data that an Integration Module requires. For more information see the links to reference documentation.

Class/type name Description Header file

TLbsAssistanceDataItem

The class defines the type of assistance data that an Integration Module requires. A bitmask of type TLbsAssistanceDataGroup is composed of TLbsAssistanceDataItem values. The class and the bitmask are used to pass requests for assistance data between the Integration Module and the LBS subsystem.

LbsAssistanceDataBase.h

TLbsAssistanceDataGroup

Bitmask of TLbsAssistanceDataItem values.

LbsAssistanceDataBase.h

RDataBuilderRootBase

Base class of readers for assistance data. Each type of assistance data requires its own reader that is derived from RDataBuilderRootBase.

LbsAssistanceDataBase.h

Table 2 Assistance data classes passed across the API

Table 3 lists position info classes that are passed across the API from an Integration Module to the LBS subsystem. For more information see the links to reference documentation.

Class/type name Description Header file

TPositionInfoBase

Base class for classes that hold GPS position fixes or GPS measurements.

LbsPositionInfo.h

TPositionSatelliteInfo

Holds a position fix and satellite information.

LbsSatelliteInfo.h

TPositionGpsMeasurementInfo

Holds GPS measurements.

LbsGpsMeasurement.h

Table 3 Position Info classes

Libraries

The main classes of the A-GPS Location Data Source API are packaged in lbslocdatasource.dll. Integration Module implementations link to lbslocdatasource.lib.

Assistance data classes are packaged in lbsassistancedata.dll. Clients link to lbsassistancedata.lib.

Position info classes are packaged in lbsselflocate.dll. Clients link to lbsselflocate.lib.

Using the A-GPS Location Data Source API

Licensees use the API to create an Integration Module to interface their device GPS hardware with the LBS subsystem. The API provides the means by which the LBS subsystem and an Integration Module interact. Details of how the Integration Module interact with the GPS hardware are hardware-specific and are not part of the API.

This section describes how an Integration Module and the LBS subsystem use the API to interact. It is intended to give a description of the general order in which the API methods are called by the LBS subsystem and to give a better understanding of their purpose.

The behaviour of an A-GPS Integration Module can be complex when it is linked to a Network Protocol Module. Several detailed end-to-end sequence diagrams that document the behaviour of the LBS subsystem including the behaviour expected from an Integration Module are given in LBS Sequence Diagrams.

Figure 2 shows a simplified sequence for an MO-LR self locate (a self-locate request from the Location Acquisition API). Terminal based positioning involves obtaining assistance data (and possibly a reference position) from the network via a Network Protocol Module. The discussion that follows describes the main flow of events for MO-LR self locate.

Figure 2. Figure 2. Simplified sequence for MO-LR self locate request

The following explains a simple flow of events between the LBS subsystem and an A-GPS Integration Module (for terminal based positioning):

In addition to the typical flow of events described, a module can also notify LBS of GPS device status changes and quality status changes.

The implementation of CLbsLocationSourceGpsBase methods must not call MLbsLocationSourceGpsObserver methods or stack overflow may eventually occur. The exception to this rule is CLbsLocationSourceGpsBase::AssistanceDataEvent(): implementations may call MLbsLocationSourceGpsObserver::GetAssistanceDataItem() multiple times to get all the request assistance data items.

Each of the steps above and shown in figure 2 is described in more detail in the following sections, with links to API reference documentation.

LBS loads the A-GPS Integration Module

The Integration Module is packaged as an ECOM plug-in DLL. When the LBS subsystem starts up, the A-GPS Location Manager process uses the ECOM framework to load the Integration Module. The A-GPS Location Manager calls CLbsLocationSourceGpsBase::NewL(), passing a reference to itself as an MLbsLocationSourceGpsObserver and the ID of the ECOM implementation DLL to load.

For more information about how to configure LBS to use an Integration Module see LBS integration and configuration guide.

LBS sets GPS options (including the GPS mode)

The GPS mode specifies how the A-GPS Integration Module should obtain a location fix. There are four modes supported by the LBS subsystem as described in GPS modes:

  • Autonomous mode

  • Terminal based mode (TB)

  • Terminal assisted mode (TA)

  • Simultaneous TB + TA

GPS mode settings values

The LBS subsystem calls CLbsLocationSourceGpsBase::SetGpsOptions() to set the GPS mode. The LBS subsystem calls this method when an Integration Module is first loaded by the LBS subsystem and when an MO-LR begins (when the setting value is taken from the LBS administration setting value for KLbsSettingHomeGpsMode).

As shown in figure 2, SetGpsOptions() may be called again as part of a location request if the network requests a different GPS mode from the one that is currently set. The mode that is set should be used by the Integration Module for all further location requests until the next call from LBS to SetGpsOptions().

Table 1 shows a list of values of CLbsAdmin::TGpsMode that are passed in SetGpsOptions().

TGpsMode Meaning

EGpsPreferTerminalBased

Prefer Terminal Based (PTB): Integration module should use Terminal Based Positioning (TB) if possible. If TB is not possible then fallback to autonomous mode.

EGpsAutonomous

Use Autonomous GPS: Module must not request any assistance data from the network and calculate a position without it.

EGpsPreferTerminalAssisted

Prefer Terminal Assisted (PTA): Module must use Terminal Assisted Positioning (TA) if possible. If TA is not possible then fallback to autonomous mode if possible.

EGpsAlwaysTerminalAssisted

Always Terminal Assisted (ATA): Module must always use TA and return an error if this is not possible. If the Integration Module is not able to use TA it calls MLbsLocationSourceGpsObserver::UpdateLocation() with a status code of KErrNotSupported.

EGpsAlwaysTerminalBased

Always Terminal Based (ATB): Module must always use TB and return an error if this is not possible. This value is not currently supported.

Table 1. TGpsMode values and their meanings.

A licensee's Integration Module is not required to support all of these modes. Licensees modify the Integration Module module.ini file DeviceGpsModeCaps setting to publish a module's capabilities to the LBS subsystem.

Valid values of DeviceGpsModeCaps in module.ini are as follows:

  • 0001 - Module supports Terminal Based positioning and is also able to calculate position autonomously if assistance data is unavailable or does not arrive on time (for example a fix is obtained before assistance data delivery).

  • 0010 - Module supports Terminal Assisted positioning. The module may (but does not have to) be able to calculate position autonomously if Terminal Assisted positioning does not succeed (for example the network is unavailable).

  • 0011 - Module supports Terminal Based positioning OR Terminal Assisted positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (for example a fix is obtained before assistance data delivery).

  • 0100 - Module can perform Terminal Assisted AND Terminal Based positioning at the same time (TB + TA). It is also able to calculate position autonomously if assistance data is unavailable (e.g. network error), or does not arrive on time (e.g. a fix is obtained before assistance data delivery). NOTE: If this bit is set then it is not necessary to set either of the less significant 2 bits as they are implied.

If DeviceGpsModeCaps is not specified in this file, LBS assumes that the module can support both Terminal Based AND Terminal Assisted GPS modes at the same time.

There are two slightly different methods of specifying the GPS mode to an Integration Module. Both methods involve the A-GPS Location Manager calling CLbsLocationSourceGpsBase::SetGpsOptions():

Setting a single positioning mode

(For autonomous mode, terminal based mode and terminal assisted mode)

LBS creates an object of class TLbsGpsOptions and calls TLbsGpsOptions::SetGpsMode() with a single parameter of type CLbsAdmin::TGpsMode:

To set the Integration Module to use autonomous mode, LBS calls SetGpsMode() with the parameter value CLbsAdmin::EGpsAutonomous.

To set terminal based mode, LBS calls SetGpsMode() with the parameter value CLbsAdmin::EGpsPreferTerminalBased. This specifies that a GPS position fix is required from the Integration Module (the module should use TB if possible, but fallback to autonomous mode if no assistance data is available).

To set terminal assisted mode, LBS calls SetGpsMode() with the parameter value CLbsAdmin::EGpsPreferTerminalAssisted or CLbsAdmin::EGpsAlwaysTerminalAssisted. This specifies that GPS measurements are required from the module. The two parameter values have the following meanings:

  • EGpsPreferTerminalAssisted means that a module should use TA if possible but fallback to autonomous mode if this is not possible (for example a network error).

  • EGpsAlwaysTerminalAssisted means that a module should always use TA. If TA is not possible (for example because of a network error) then the Integration Module must signal an error by calling MLbsLocationSourceGpsObserver::UpdateLocation() with an error status code (a negative code).

To set the GPS mode on the Integration Module, LBS calls CLbsLocationSourceGpsBase::SetGpsOptions() passing the TLbsGpsOptions reference as a parameter.

If LBS attempts to set an Integration Module's GPS mode to one that it does not support then the Integration Module must call MLbsLocationSourceGpsObserver::UpdateLocation() with a status parameter of KErrNotSupported. Note that the Symbian reference A-GPS Integration Module does not support Terminal Assisted mode or TB + TA mode.

As part of a location request, the network can specify the required GPS modes to LBS (see Network Protocol Module documentation for more information about how a Protocol Module specifies these modes). If the network asks for Terminal Assisted mode, the LBS subsystem uses the value of the administration setting KLbsSettingHomeGpsMode to decide which mode is sent to the Integration Module, either EGpsPreferTerminalAssisted or EGpsAlwaysTerminalAssisted.

Setting multiple positioning modes (TB + TA)

The network can specify two positioning modes that LBS should use (see Network Protocol Module for more information about how the modes are specified to LBS).

If the Integration Module is capable of supporting both TB and TA simultaneously (DevGpsModeCaps = 0100 in module.ini) then LBS specifies both modes to a module as follows:

LBS creates an object of class TLbsGpsOptionsArray. Each element of the array is a TLbsGpsOptionsItem object which can hold one of two values of type TLbsGpsOptionsItem::TPosUpdateType, set by calling TLbsGpsOptionsItem::SetLocUpdateType():

  • TLbsOptionsItem::EPosUpdateCalculation specifies that a calculated position is required from the Integration Module

  • TLbsOptionsItem:EPosUpdateMeasurement specifies that a set of GPS measurements are required from the Integration Module

LBS creates an array with two TLbsGpsOptionsItem elements, the first of type TLbsOptionsItem::EPosUpdateCalculation and the second of type TLbsOptionsItem:EPosUpdateMeasurement.

LBS calls TLbsGpsOptions::SetGpsMode() with a parameter value of EGpsPreferTerminalBased. To set the GPS mode on the Integration Module, LBS calls CLbsLocationSourceGpsBase::SetGpsOptions() passing the TLbsGpsOptions reference as a parameter.

The type and position of the elements in the array controls the type of data the Integration Module returns when it notifies LBS of a location update.

LBS sends power advice

Power advice messages are sent from LBS to notify the Integration Module that it should change its power status. Power advice is sent by LBS calling CLbsLocationSourceGpsBase::AdvisePowerMode(), passing a CLbsLocationSourceGpsBase::TPowerMode value as a parameter. The Integration Module must implement its own code to control the power mode of the GPS hardware. The meanings of the TPowerMode values are as follows:

TPowerMode Meaning

EPowerModeOn

Advise the module to turn on GPS hardware power

EPowerModeStandby

Advise the module to set the GPS hardware power to standby

EPowerModeOff

Advise the module to turn off GPS hardware power

EPowerModeClose

Advise the module that the LBS subsystem is shutting down

When the GPS hardware changes its power mode the Integration Module must notify LBS of a device status change by calling MLbsLocationSourceGpsObserver::UpdateDeviceStatus(). This message not shown on figure 2.

LBS requests a location update (for a GPS position fix or GPS measurements)

LBS calls CLbsLocationSourceGpsBase::RequestLocationUpdate() to request a location update. The method should be implemented to return as soon as possible. At some later time the A-GPS Integration Module informs LBS that a location update is available by calling MLbsLocationSourceGpsObserver::UpdateLocation().

The full signature of the method is RequestLocationUpdate(const TTime &aTargetTime, const TLbsLocRequestQuality &aQuality).

aTargetTime specifies when a location update is required. When the GPS module responds by calling MLbsLocationSourceGpsObserver::UpdateLocation() it is aTargetTime that is used to couple a location update request and response within the LBS subsystem. Therefore an Integration Module must use aTargetTime to identify the response to LBS.

aQuality specifies quality criteria for the request including the required position accuracy and a MaxFixTime which is the maximum time that the Integration Module should spend processing the location request. If the Integration Module is not capable of delivering a position within MaxFixTime then it must return an incomplete update. See the section Module notifies LBS of a location update for more details.

Module requests assistance data (if necessary)

Depending on the GPS mode that was set before the location request was made and the age of any assistance data it may already have, an A-GPS Integration Module may request assistance data from the LBS subsystem by calling MLbsLocationSourceGpsObserver::RequestAssistanceData().

The Integration Module specifies the type of assistance data it requires by creating a TLbsAsistanceDataGroup bitmask which contains bit values from the TLbsAssistanceDataItem enumeration. Each value of TLbsAssistanceDataItem specifies a particular type of assistance data.

The module passes a bitwise OR of TLbsAssistanceDataItem values as a TLbsAsistanceDataGroup parameter in a call to MLbsLocationSourceGpsObserver::RequestAssistanceData().

Notes:

  1. Calling RequestAssistanceData() causes LBS to retrieve new assistance data from the network. The LBS subsystem caches assistance data when it is retrieved. Before calling RequestAssistanceData() for new assistance data it is most efficient for an Integration Module to check the timestamp of the assistance data cached by LBS by calling MLbsLocationSourceGpsObserver::GetAssistanceDataItemTimeStamp(). The Integration Module can use the returned timestamp to decide if it the assistance data is still valid, or if it needs to obtain new data by calling RequestAssistanceData().

    A licensee can implement an Integration Module to have its own assistance data cache. An Integration Module can be instructed to reset its assistance data cache. See Resetting A-GPS assistance data for more information.

  2. If a Integration Module does not require assistance data (possibly because the assistance data it currently has is still accurate) then it must respond to RequestLocationUpdate() by calling RequestAssistanceData() with a parameter bitmask=0.

LBS notifies the A-GPS Integration Module of assistance data availability

When LBS obtains assistance data from the network it informs the module by calling CLbsLocationSourceGpsBase::AssistanceDataEvent(). As shown in figure 2, this method may be called multiple times as new assistance data arrives from the network. LBS can call this method to deliver assistance data at any time, not just immediately after a module calls RequestAssistanceData().

The type of assistance data available is indicated by a TLbsAsistanceDataGroup bitmask parameter which contains TLbsAssistanceDataItem values.

Note: This method is used to notify LBS of a network error during a location request in which case the status parameter is set to a negative error code (a network or network protocol specific error code).

Module retrieves A-GPS assistance data items

When it is notified that assistance data is available, the A-GPS Integration Module uses MLbsLocationSourceGpsObserver::GetAssistanceDataItem() to get obtain it.

Where more than one item of assistance data is available (as indicated by the TLbsAsistanceDataGroup bitmask parameter passed with CLbsLocationSourceGpsBase::AssistanceDataEvent()) it is necessary to call GetAssistanceDataItem() for each item.

Module notifies LBS of a location update

When the Integration Module calculates a GPS position fix or has obtained GPS position measurements it calls MLbsLocationSourceGpsObserver::UpdateLocation(). The parameter list of UpdateLocation() is as follows:

void UpdateLocation(TInt aStatus, const TPositionInfoBase *aPosInfoArray[], TInt aNumItems, const TTime &aTargetTime);

aPosInfoArray is a return parameter that is a pointer to an array of TPositionInfoBase objects. What an Integration Module returns in this parameter depends on the GPS positioning mode that was set by calling CLbsLocationSourceGpsBase::SetGpsOptions().

  • Autonomous mode and Terminal Based mode

    The Integration Module returns a pointer to a single TPositionSatelliteInfo object. It contains a position fix and GPS satellite details. The position fix may be incomplete if the Integration Module was unable to calculate the position completely before the MaxFixTime (specified as part of the location request) expired. For example, a position may be returned that contains only horizontal but not vertical co-ordinates. Missing co-ordinate values are set to NaN.

    Up until MaxFixTime, an Integration Module calls MLbsLocationSourceGpsObserver::UpdateLocation() whenever it has calculated a more accurate or complete position fix.

  • Terminal Assisted mode

    The Integration Module returns a pointer to a single TPositionGpsMeasurementInfo object. It contains a set of GPS measurements, but not a position fix.

    Up until MaxFixTime, an Integration Module calls MLbsLocationSourceGpsObserver::UpdateLocation() whenever it obtains additional GPS measurements. Measurements are sent to the network where they are used to calculate a position.

  • Terminal Based mode + Terminal Assisted mode (TB + TA)

    The Integration Module returns a pointer to an array of elements derived from class TPositionInfoBase.

    Specifically, the array has elements of the derived classes TPositionSatelliteInfo and TPositionGpsMeasurementInfo. The number and type of elements returned must be as specified by LBS when it set the GPS mode. In practice, this means that the array returned by an Integration Module must have two elements:

    As in TA and TB modes, the Integration Module calls MLbsLocationSourceGpsObserver::UpdateLocation() whenever it obtains additional GPS measurements or calculates a more accurate or complete position fix (up until the location request MaxFixTime).

Error codes

An Integration Module must return a location update (positions and/or measurements) by the MaxFixTime that was specified by LBS in CLbsLocationSourceGpsBase::RequestLocationUpdate(). If an Integration Module has only incomplete data by MaxFixTime it must return it (aStatus == KErrNone).

If an Integration Module decides that it will be unable to calculate a position fix with the specified quality criteria, then rather than waiting until MaxFixTime it can return its best available position (which may be incomplete or contain invalid data) with aStatus == KPositionCalculationFutile.

Cancelling a location update request

LBS can cancel an outstanding location request by calling CLbsLocationSourceGpsBase::CancelLocationRequest() (not shown on figure 2).

Resetting A-GPS assistance data

During testing it is useful to be able to reset some or all of the A-GPS assistance data cached by an Integration Module. One of the main benefits is to allow the Time To First Fix (TTFF) of a module to be tested without the need to restart the LBS subsystem or the mobile device.

A licensee Network Protocol Module calls MLbsNetworkProtocolObserver::ProcessAssistanceData() to tell the LBS subsystem to reset some or all of its assistance data. The Network Protocol Module passes a parameter value of KPositionAssistanceDataReset to specify that LBS must clear the assistance data in its cache and a TLbsAssistanceDataGroup parameter to specify the bitmask of types of assistance data that must be reset.

LBS responds by clearing the specified types of assistance data in its own cache. It also calls CLbsLocationSourceGpsBase::AssistanceDataEvent() on the Integration Module with a KPositionAssistanceDataReset parameter to specify an assistance data reset and a TLbsAssistanceDataGroup parameter to specify the bitmask of types of assistance data that must be reset. If the licensee A-GPS Integration Module implements its own assistance data cache it must clear the types of assistance data specified by LBS.

Figure 3 shows a simple sequence for assistance data reset, followed by the start of an MO-LR.

Figure 3. Figure 3. Assistance data reset before location request

GPS hardware device status changes and quality status changes

(Not shown on figure 2)

Device status changes

When the base GPS hardware changes its power mode the Integration Module must notify LBS by calling MLbsLocationSourceGpsObserver::UpdateDeviceStatus().

Quality status changes

If an Integration Module detects that there is a change in the quality of position it is able to provide it must notify LBS by calling MLbsLocationSourceGpsObserver::UpdateDataQualityStatus().

See here for more information about how client applications can get updates of device status changes and quality status changes.

Integration module configuration

In addition to coding the Integration Module, there are configuration steps that a licensee must complete:

Create a GPS Integration Module .ini file

The GPS Integration Module .ini file identifies a GPS 'source of location' to LBS. This is the pairing of the GPS/A-GPS Integration Module ECom plug-in with the A-GPS Location Manager process.

The module .ini file created by a device creator for their own Integration Module must have the same layout as the following example and it must be exported to <rom_drive>:\private\10282253\lbs\locmods\ (10282253 is the UID3 of the LBS Root process). 


# example_datasource.ini
[1]
Version= 0.2.1        #
ModuleId= 271064388    # dec
ModuleName= "Example_AGPS_Module”
TechnologyType= 0101    # binary
DeviceLocation= 1    # binary
Capabilities= 11111    # binary
ClassesSupported= 111111    # binary
TimeToFirstFix= 90000    # ms
TimeToNextFix= 1000    # ms
HorizontalAccuracy= 5.4 # real
VerticalAccuracy= 5.4 # real
CostIndicator= 2    # dec
PowerConsumption= 2    # dec
DataSourceId= 271065673    # dec
ExecutableName= "lbsgpslocmanager.exe"
DeviceGpsModeCaps=1011    # binary - Exclusive TA OR TB (+ Autonomous)

The table below describes each of the values in a module .ini file.

Note: the ModuleId UID is decimal and must be the UID of the A-GPS Location Manager process. The DataSourceId UID is also decimal and is the implementation UID of the Integration Module ECOM plug-in.

Parameter Type Description

Version

A string

The GPS Integration Module version.

ModuleId

A UID (decimal)

The UID3 of the location manager process that uses this GPS Integration Module.

TechnologyType

A binary value from TPositionModuleInfo::_TTechnologyType

The technology types the module supports: one or more of handset based, network based or network assisted.

DeviceLocation

A bitmask value from TPositionModuleInfo::_TDeviceLocation

Specifies whether the GPS Integration Module is internal or external to the handset. Currently only internal modules are supported. Defined in LbsCommon.h.

Capabilities

A bitmask value from TPositionModuleInfo::_TCapabilities

A bitmask value that defines the capabilities of this module (such as the ability to provide vertical position and speed data). Defined in LbsCommon.h.

ClassesSupported

A bitmask value from _TPositionInfoClassType

A bitmask value that defines the class types that are supported by this module. Defined in LbsClassTypes.h.

TimeToFirstFix

An integer value

The time to get the first location fix (in milliseconds)

TimeToNextFix

An integer value

The time to get subsequent location fixes after the first location fix (in milliseconds).

HorizontalAccuracy

A real value

The maximum accuracy of horizontal position that the module can supply (in metres). For example 100 if the location fix is accurate to within 100m.

VerticalAccuracy

A real value

The maximum accuracy of vertical position that the module can supply (in metres).

CostIndicator

A value from TPositionQuality::TCostIndicator

A qualitative measure of the financial cost to the handset owner of using this module to obtain a location fix. Defined in LbsCommon.h.

PowerConsumption

A value from TPositionQuality::TPowerConsumption

A qualitative measure of the power consumption of using this module to obtain a location fix. Defined in LbsCommon.h.

DataSourceId

A UID (decimal)

The UID3 of the module ECOM plug-in.

ExecutableName

A string

The name of the location manager process that uses this module.

DeviceGpsModeCaps

A binary value

The positioning modes supported by the module. The values are defined in LbsExtendModuleInfo.h. Possible values are:

0001 - Module supports Terminal Based positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (e.g. a fix is obtained before assistance data delivery).

0010 - Module supports Terminal Assisted positioning. The module may, but does not have to be able to calculate position autonomously if Terminal Assisted positioning does not succeed (e.g. network is unavailable).

0011 - Module supports Terminal Based positioning OR Terminal Assisted positioning and is also able to calculate position autonomously if assistance data is unavailable, or does not arrive on time (e.g. a fix is obtained before assistance data delivery).

0100 - Module can perform Terminal Assisted AND Terminal Based positioning at the same time. It is also able to calculate position autonomously if assistance data is unavailable (e.g. network error), or does not arrive on time (e.g. a fix is obtained before assistance data delivery). NOTE: If this bit is set then it is not necessary to set either of the less significant 2 bits as they are implied.

If DeviceGpsModeCaps is not specified in this file, LBS assumes that the module can support both Terminal Based AND Terminal Assisted GPS modes at the same time.

Create an Integration Module .rss file

A GPS Integration Module is implemented as an ECOM plug-in and has a .rss resource file that specifies the UIDs of the interface and the implementation class.

The value of DataSourceId in the module .ini file is decimal and must be equal to the hexadecimal implementation_uid value specified in the module ECOM .rss file.

An example .rss file is shown below. The implementation_uid value of 0x10282249 is the hexadecimal value of the DataSourceId value of 271065673 specified in example_datasource.ini above. 

// example_datasource.rss
//
// The Example Data Source resource file

#include "ecom/registryinfov2.rh"

RESOURCE REGISTRY_INFO theInfo
    {
    resource_format_version = RESOURCE_FORMAT_VERSION_2;
    dll_uid = 0x10281D6D;
    interfaces =
        {
        INTERFACE_INFO
            {
            interface_uid = 0x10281D73;
            implementations = 
                {
                IMPLEMENTATION_INFO
                    {
                    implementation_uid = 0x10282249;
                    version_no = 1;
                    display_name = "Example GPS Module";
                    default_data = "";
                    opaque_data = "";
                    rom_only = 0;
                    }
                };
            }
        };
     }

The module.ini file described in the LBS integration and configuration guide must be modified to describe the capabilities of the Integration Module. Parameters that may need to be changed by licensees include the time to get a first fix and the accuracy of position fixes that can be delivered.

Update the LBS administration settings

The LBS administration setting KLbsSettingHomeGpsMode (and KLbsSettingRoamingGpsMode) must be set. The settings specify the default GPS positioning mode that LBS sets for the Integration Module. A default value can be specified in the administration repository initialisation file and it can also be set at runtime via the LBS Administration API. The set of GPS positioning mode values are defined by CLbsAdmin::TGpsMode.

Note : When the network is involved in a location request (which it is for any GPS mode other than autonomous) it can request a GPS mode that overrides the administration setting. For more information about how the positioning mode is set and the behaviour that the LBS subsystem expects from an Integration Module see LBS sets GPS options.

Parent topic: A-GPS Location Data Source API

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.