Network Protocol Module API

Contents

• Purpose

• Introduction

• Network Protocol Module API description

• Using the Network Protocol Module API

• Network Protocol Module configuration

• Loading the Network Protocol Module

• See also

Purpose

A Network Protocol Module is an ECOM plug-in that provides network connectivity for the LBS subsystem. A Network Protocol Module typically supports one Location Based Services network protocol. Location Based Services network protocols are used by the LBS subsystem for the following purposes:

• To receive location requests from the network.

• To send requests for A-GPS assistance data to the network and to receive it.

• To send GPS-calculated positions and GPS measurements to the network and to receive calculated positions from the network.

Network Protocol Modules can be classified into two groups, depending on the network operator's network architecture that they are intended to interface with:

• Control plane architectures use the circuit-switched mobile network and signalling layer to support Location Based Services.

  To integrate the Symbian LBS subsystem with a control plane architecture, a Symbian licensee must implement their own control plane Network Protocol Module using the Network Protocol Module API described in this document.

• User plane architectures use IP bearers independently of the circuit-switched signalling layer. SMS or WAP Push can also be used to initiate location requests. The OMA Secure User Plane Location (SUPL) architecture describes a model for supporting IP-based Location Based Services.

  Symbian provides a reference SUPL Protocol Module that supports the OMA SUPL v1.0 standard, using the 3GPP Radio Resource LCS Protocol (RRLP) as the protocol payload. The reference SUPL Protocol Module implements the Network Protocol Module API.

LBS architecture overview gives more details of how a Network Protocol Module fits into the LBS subsystem.

Introduction

A Network Protocol Module is an ECOM plug-in DLL. It communicates with the LBS Network Gateway process via the Network Protocol API and with the network via either the ETel or ESock APIs as shown in figure 1.

A Network Protocol Module has several functions:

• Translating method calls from the LBS subsystem into protocol specific messages which are sent over the network

• Translating protocol specific messages received from the network into method calls on the LBS subsystem

• Queueing and prioritising messages received from the network and messages to be sent to the network

• Performing conflict resolution when a request is made which conflicts with ongoing location requests being processed by the LBS subsystem

Licensees can configure the LBS subsystem to load a different Network Protocol Module when the mobile device is in the home network and when roaming. For example, it is possible to configure LBS to load a licensee control plane Network Protocol Module in the home network and the Symbian reference SUPL Protocol Module when roaming. See Loading the Network Protocol Module for more details.

A Symbian licensee must create a Network Protocol Module to integrate the Symbian LBS subsystem with a control plane architecture. A control plane Network Protocol Module uses the ETel API and the telephony stack for network communications. Symbian does not provide a reference control plane Network Protocol Module.

Symbian provides a reference Network Protocol Module that implements the SUPL v1.0 user plane architecture with RRLP as the protocol data payload. See SUPL Protocol Module documentation for more information about this reference module. The SUPL Protocol Module may meet the requirements of Symbian licensees and network operators and so it may not be necessary for licensees to create a custom Network Protocol Module using the API described in this document.

Symbian also provide a Test Network Protocol Module as part of the LBS subsystem code distribution which can be found at <LBS_ROOT>\LbsProtocolModule. The test protocol module is not a production quality module for use in a mobile device, neither is it a reference implementation. Its main purpose is to facilitate Symbian's own testing of the LBS subsystem.

Network Protocol Module API description

This section describes the classes of the Network Protocol Module API.

API class diagram

A Network Protocol Module and the LBS Network Gateway process communicate using the Network Protocol Module API. The API consists of classes in an observer/observable design pattern.

Figure 2 shows the main classes of the Network Protocol Module API. Note that this diagram does not list all of the classes of the API and excludes numerous T classes that are used as method parameters.

Note that the virtual methods of CLbsNetworkProtocolBase and CLbsNetworkProtocolBase2 are synchronous and their implementations must return quickly (for example by queueing requests and returning immediately).

API classes and types

Table 1 lists the main classes of the Network Protocol Module API. Further details about the classes can be found by following the links to reference documentation.

The main classes are defined in lbsnetprotocolbase.h. Additional API classes and types that are used as API method parameters are defined in lbsnetcommon.h and lbsnetclasstypes.h.

The Network Protocol Module API has publishedPartner interface access.

Table 1 Classes of the Network Protocol Module API.

Network Protocol Modules derive from CLbsNetworkProtocolBase or CLbsNetworkProtocolBase2. The LBS subsystem implements the MLbsNetworkProtocolObserver interface to interact with a Network Protocol Module.

Libraries

The main classes of the Network Protocol Module API are packaged in lbsnetprotocol.dll. Network Protocol Module implementations link to lbsnetprotocol.lib.

LBS configuration

In addition to creating and installing a Network Protocol Module, the LBS administration settings KLbsSettingHomeProtocolModule and KLbsSettingRoamingProtocolModule must be set to the implementation UIDs of the appropriate Network Protocol Module ECOM plug-ins for LBS to load and use them. See Loading the Network Protocol Module for more information.

Using the Network Protocol Module API

A Network Protocol Module communicates with two other software components:

• The LBS Network Gateway process

  The Network Gateway process communicates with the other components of the LBS subsystem. It is responsible for:

  1. Handling requests for location from the LBS subsystem and sending them to the network via the Network Protocol Module

  2. Receiving a reference position (based on Cell ID) from the network via the Network Protocol Module and sending it into LBS in response to 1.

  3. Handling requests for A-GPS assistance data from an A-GPS Integration Module and sending them to the network via the Network Protocol Module

  4. Receiving A-GPS assistance data from the network via the Network Protocol Module and sending it to the A-GPS Location Manager in response to 3.

  5. Handling requests from the LBS subsystem to send device location data to a third party over the network (MO-LR transmit to third party).

  6. Receiving privacy requests and location requests from the network (MT-LR and Emergency MT-LR) via the Network Protocol Module and forwarding them to the LBS subsystem.

  7. Sending responses to MT-LR privacy requests and location requests to the network via the Network Protocol Module in response to 6.

• A network communications stack

  A Network Protocol Module that integrates with the control plane uses the Symbian ETel API.

  A Network Protocol Module that integrates with the user plane uses the Symbian ESock API. The Symbian reference SUPL Protocol Module is a user plane Network Protocol Module.

Figures 3, 4 and 5 show simple sequences of interaction between the LBS Network Gateway process, the Network Protocol Module and the network for MO-LR (self locate), MO-LR (transfer to third party) and MT-LR.

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

CLbsNetworkProtocolBase

The following briefly describes the CLbsNetworkProtocolBase methods grouped according to their function. The LBS Network Gateway process calls these methods on the licensee Network Protocol Module. More detailed information about the purpose of these methods and their parameter lists can be found by following the links to the Symbian platform reference documentation.

Setting tracking mode (if necessary)

For MO-LR self locate, an application client can ask the LBS subsystem for periodic location updates. This is known as tracking and is described in the Location Acquisition API document How to get location information.

When a client requests tracking, the LBS subsystem notifies a Network Protocol Module of this requirement by calling CLbsNetworkProtocolBase::AdviceSystemStatus() with a parameter value CLbsNetworkProtocolBase::ESystemStatusClientTracking. This method is called before the first location request CLbsNetworkProtocolBase::RequestSelfLocation() described below.

When there are no longer any tracking LBS clients, the LBS subsystem notifies a Network Protocol Module by calling AdviceSystemStatus() with a parameter value CLbsNetworkProtocolBase::ESystemStatusNone.

Requesting and cancelling MO-LR (self locate)

• CLbsNetworkProtocolBase::RequestSelfLocation()

  This method is called to initiate an MO-LR (self locate) when GPS is to be used to obtain a location. In cases where the precision of a GPS fix is not required (for example because of less demanding location quality criteria), the method CLbsNetworkProtocolBase::RequestNetworkLocation() may be called instead for MO-LR (see below).

• CLbsNetworkProtocolBase::CancelSelfLocation()

  This method is called to cancel an outstanding MO-LR which was made by calling CLbsNetworkProtocolBase::RequestSelfLocation().

Requesting and cancelling MO-LR (self locate) from the network

• CLbsNetworkProtocolBase::RequestNetworkLocation()

  This method is called to initiate an MO-LR when the precision of GPS is not required. In cases where the precision of a GPS fix is required, the method CLbsNetworkProtocolBase::RequestSelfLocation() is called instead.

• CLbsNetworkProtocolBase::CancelNetworkLocation()

  This method is called to cancel an outstanding MO-LR which was made by calling CLbsNetworkProtocolBase::RequestNetworkLocation().

Requesting and cancelling of MO-LR (transmit to third party)

• CLbsNetworkProtocolBase::RequestTransmitLocation()

  This method is called to send location to a third party.

• CLbsNetworkProtocolBase::CancelTransmitLocation()

  This method is called to cancel an outstanding request to send location to a third party.

Responding to MT-LR privacy requests

• CLbsNetworkProtocolBase::RespondPrivacyRequest()

  This method is called in response to an MT-LR privacy request in order to accept or reject the request.

  See Privacy requests for more information about how privacy requests are handled by the LBS subsystem.

Processing location requests

As shown in figures 3, 4 and 5, MO-LR self locate, MO-LR transfer to third party and MT-LR cause the Network Protocol Module to call MLbsNetworkProtocolObserver::ProcessLocationRequest() on the LBS Network Gateway process.

An instance of TLbsNetPosRequestMethod is passed when the Protocol Module calls MLbsNetworkProtocolObserver::ProcessLocationRequest(). It defines the type(s) of positioning method the LBS subsystem should use to calculate the device location.

A Network Protocol Module can specify up to two positioning methods, if required: TLbsNetPosRequestMethod contains an array of elements of type TLbsNetPosMethod. Each TLbsNetPosMethod element specifies a technology type and the positioning mode that should be used by the LBS subsystem to calculate location.

If the array contains two elements, the first element contains the preferred technology type and positioning mode. The second element contains an alternative positioning mode.

If the array contains only one element then this specifies the technology type and positioning mode that must be used by the LBS subsystem.

Examples of how a Network Protocol Module specifies the positioning mode follows:

• Terminal based positioning mode only

  The Protocol Module creates a single TLbsNetPosMethod element and calls TLbsNetPosMethod::SetPosMethod() passing the parameters:

  aPosMeans = KLbsPositioningMeansGps

  aPosMode = TPositionModuleInfo::ETechnologyTerminal | TPositionModuleInfo::ETechnologyAssisted

  In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network.

• Terminal assisted positioning mode only

  The Protocol Module creates a single TLbsNetPosMethod element and calls TLbsNetPosMethod::SetPosMethod() passing the parameters:

  aPosMeans = KLbsPositioningMeansGps

  aPosMode = TPositionModuleInfo::ETechnologyNetwork | TPositionModuleInfo::ETechnologyAssisted

  In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network.

• Terminal based positioning mode (1st choice) & terminal assisted positioning mode (2nd choice)

  The Protocol Module creates two TLbsNetPosMethod elements and calls TLbsNetPosMethod::SetPosMethod() for each:

  • 1st Element:

    aPosMeans = KLbsPositioningMeansGps

    aPosMode = TPositionModuleInfo::ETechnologyTerminal | TPositionModuleInfo::ETechnologyAssisted

  • 2nd Element:

    aPosMeans = KLbsPositioningMeansGps

    aPosMode = TPositionModuleInfo::ETechnologyNetwork | TPositionModuleInfo::ETechnologyAssisted

  In this case, the LBS subsystem attempts to calculate a GPS location fix using assistance data from the network. While LBS is calculating a GPS fix it also returns GPS measurements to the Network Protocol Module.

• Position from the network (cell based positioning)

  The Protocol Module creates a single TLbsNetPosMethod element and calls TLbsNetPosMethod::SetPosMethod() passing the parameters:

  aPosMeans = KLbsPositioningMeansCell

  aPosMode = TPositionModuleInfo::ETechnologyNetwork

  In this case, the LBS subsystem uses the reference location from the network as the location fix.

Calling MLbsNetworkProtocolObserver::ProcessLocationRequest() causes the LBS subsystem to begin to calculate a location (or begin to obtain GPS measurements necessary to calculate a location). When location data is available, the LBS Network Gateway process calls CLbsNetworkProtocolBase::RespondLocationRequest().

Requesting A-GPS assistance data

• CLbsNetworkProtocolBase::RequestAssistanceData()

  This method is called to get additional A-GPS assistance data as part of an MO-LR (self locate), MO-LR (transfer to third party) or an MT-LR. Assistance data identifies the satellites that should be visible from the current mobile device location and this reduces the time required to obtain GPS measurements.

MLbsNetworkProtocolObserver

The following briefly describes the MLbsNetworkProtocolObserver methods grouped according to their function. A licensee Network Protocol Module calls these methods on the LBS Network Gateway process. More detailed information about the purpose of these methods and their parameter lists can be found by following the links to the Symbian platform reference documentation.

Getting the current capabilities of the LBS subsystem

• MLbsNetworkProtocolObserver::GetCurrentCapabilities()

  This method is called by the Network Protocol Module to get the capabilities of the LBS subsystem, such as whether it can calculate a GPS location fix and the supported GPS modes. The method takes a single parameter of class TLbsNetPosCapabilities (defined in lbsnetcommon.h) that encapsulates methods to discover the protocols and positioning methods supported by the LBS subsystem.

  Note that the capabilities of the LBS subsystem can change at runtime (because of modification via the LBS Administration API) and therefore a licensee Network Protocol Module should call this method whenever it needs to check the current capabilities of the LBS subsystem.

Updating the LBS Network Gateway with the Network Protocol Module status

• MLbsNetworkProtocolObserver::ProcessStatusUpdate()

  This method is called to update the LBS subsystem with the current status of the Network Protocol Module.

  The method takes a single parameter of type MLbsNetworkProtocolObserver::TLbsNetProtocolServiceMask, a bitmask variable that indicates the types of requests currently being handled by the Network Protocol Module. This bitmask variable holds a bitwise OR of values of type MLbsNetworkProtocolObserver::TLbsNetProtocolService.

  A Network Protocol Module calls this method to inform the LBS subsystem whenever its state has changed, for example after the LBS subsystem has requested a new MO-LR or when an MT-LR is received from the network.

Notifying of MT-LR privacy requests

• MLbsNetworkProtocolObserver::ProcessPrivacyRequest()

  This method is called to indicate that an MT-LR privacy request has been received.

  See Privacy requests for more information about how privacy requests are handled by the LBS subsystem.

Requesting a location

For MO-LR (self locate) the LBS Network Gateway process calls CLbsNetworkProtocolBase::RequestSelfLocation() (for GPS positioning modes) or CLbsNetworkProtocolBase::RequestNetworkLocation() (for cell-based positioning modes).

For MO-LR (transfer to third party) the LBS Network Gateway calls CLbsNetworkProtocolBase::RequestTransmitLocation(). In response to these, or when an MT-LR location request is received, the Network Protocol Module calls MLbsNetworkProtocolObserver::ProcessLocationRequest() on the LBS Network Gateway.

A TLbsNetPosRequestMethod parameter specifies the method that should be used by the LBS subsystem to obtain the location fix.

Handling receipt of A-GPS assistance data

• MLbsNetworkProtocolObserver::ProcessAssistanceData()

  This method is called when A-GPS assistance data is received from the network. The assistance data is delivered to LBS as an RLbsAssistanceDataBuilderSet object and is cached by the LBS subsystem. A licensee A-GPS Integration Module is notified when assistance data is delivered to LBS and may request it.

Resetting A-GPS assistance data for testing

If requested to do so by the network, a licensee's Network Protocol Module can instruct the LBS subsystem and the licensee's A-GPS Integration Module to reset any cached assistance data. It does this by calling MLbsNetworkProtocolObserver::ProcessAssistanceData(), with a KPositionAssistanceDataReset parameter to tell LBS to reset its cached assistance data and a TLbsAssistanceDataGroup bitmask parameter to specify the types of assistance data to be reset. Using ProcessAssistanceData() in this way has two effects:

• LBS deletes the specified assistance data in its own assistance data cache.

• LBS calls the A-GPS Location DataSource API method CLbsLocationSourceGpsBase::AssistanceDataEvent() with a KPositionAssistanceDataReset parameter (to inform a licensee's A-GPS Integration Module that it must reset its assistance data) and a TLbsAssistanceDataGroup bitmask parameter (to specify the types of assistance data that should be reset).

Updating location data

• MLbsNetworkProtocolObserver::ProcessLocationUpdate()

  This method is called to update the LBS subsystem either:

  • When a reference position is returned from the network

    ProcessLocationUpdate() returns a TPositionInfoBase parameter which contains the reference position. Calling TPositionInfoBase::PositionMode() returns TPositionModuleInfo::ETechnologyNetwork.

  • When the 'final position' is returned from the network (for MO-LR self locate and MO-LR transfer to third party)

    The final position is the last position returned from the network. For terminal based positioning, the final position is just the position that LBS sent to the network by calling CLbsNetworkProtocolBase::RespondLocationRequest(). For terminal assisted positioning, the final position is the one calculated by the network using GPS measurements from the device.

    For a final position calculated using terminal based positioning TPositionInfoBase::PositionMode() returns TPositionModuleInfo::ETechnologyTerminal | TPositionModuleInfo::ETechnologyAssisted.

    For a final position calculated using terminal assisted positioning TPositionInfoBase::PositionMode() returns TPositionModuleInfo::ETechnologyNetwork | TPositionModuleInfo::ETechnologyAssisted.

Completing a session

• MLbsNetworkProtocolObserver::ProcessSessionComplete()

  This method is called to indicate that a session is complete (for example that a single MO-LR or MT-LR is complete).

# networklocationmanager.ini

[1]
Version= 0.1.1        #
ModuleId= 271064387    # dec
ModuleName= "NetLocManager"    # 
TechnologyType= 0010    # binary
DeviceLocation= 0010    # binary
Capabilities= 1111    # binary
ClassesSupported= 111111    # binary
TimeToFirstFix= 20000    # ms
TimeToNextFix= 20000    # ms
HorizontalAccuracy= 100 # real
VerticalAccuracy= 100 # real
CostIndicator= 3    # dec
PowerConsumption = 2 # dec
ExecutableName= "lbsnetlocmanager.exe"

#include "ecom/registryinfov2.rh"

RESOURCE REGISTRY_INFO theInfo
    {
    resource_format_version = RESOURCE_FORMAT_VERSION_2;
    dll_uid = 0x10285A9C;
    interfaces = 
        {
        INTERFACE_INFO
            {
            // UID of interface that is implemented
            interface_uid = 0x10281D4A;
            implementations = 
                {
                IMPLEMENTATION_INFO
                    {
                    // UID of this interface implementation
                    implementation_uid = 0x10285A9D;
                    version_no = 1;
                    display_name = "SUPL V1 Protocol Module";
                    default_data = "";
                    opaque_data = "";
                    rom_only = 0;
                    }
                };
            }
        };
    }
             

#KSettingHomeProtocolModule. Use reference SUPL Protocol Module
0x0000000E  int  0x10285A9D
#KSettingRoamingProtocolModule.
0x0000000F  int  0x10285A9D