S60 5.1 SUPL POS Message Plug-in API Specification

DN0999999
CONFIDENTIAL

©Nokia 2007
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.0

23.10.2006

Approved

 

1.1

08.09.2008

Draft

Added support for passing Allowed Capabilities and Positioning Method from the SUPL framework to the POS Plug-in

1.2

01.12.2008

Approved

Added support for passing SLP Address to the POS Plug-in from the SUPL framework.


Table of Contents

Changes
Purpose
Constraints
Classification and release information
Emulator support
API description
Use cases
Get SUPL Message parameters
Generate and process POS Payload
Retrieve position information from POS Message plug-in
Pass allowed capabilities from the SUPL framework to the POS Message plug-in
Pass desired positioning method from the SUPL Framework to the POS Message Plug-in
Pass Server Address from the SUPL Framework to the POS Message Plug-in
API class structure
SUPL POS Message Plug-in API data types
Using the SUPL Pos Message Plug-in API
Implementation Details
Get SUPL Message Parameters
Generate and Process POS Payload
Get Position
Providing Registry Information
Exporting a factory function
Defining the MMP file
Error handling
Memory overhead
Extensions to the API
Glossary
Abbreviations
Definitions
References

 


Changes

The following header file(s) have changed between S60 releases 3.1 and 5.1

Table:
Type Class Change
Modified Methods COMASuplPosSessionBase SetCurrentServerAddress() method is used to set the Server Address being used for this session in the POS Plug-in.

 


Purpose

Secure User Plane Location (SUPL) is used to exchange control plane positioning protocol messages (also called POS Messages) over the user plane. SUPL employs user plane data bearers for transferring location information . More details about the SUPL Protocol can be found in document[1].

SUPL Enabled Terminal (SET) and SUPL Location Platform (SLP) are the two important elements of the SUPL protocol. SUPL establishes a secure IP connection between the SET and SLP. This secure IP connection is used to exchange SUPL messages.

An adaptation SUPL Terminal Initiation client component initiates a SUPL session between the SET and SLP using the Terminal Initiation API [6]. SUPL Session can also be initiated by WAP Push listener and SMS listener using Network Initiation API [7]. Once the secure IP connection is established, the POS Message Plug-in provides and processes the control plane positioning protocol messages. More information about the SUPL Subsystem can be found in document [5].

SUPL POS Message Plug-in API defines classes required for licensees to implement POS Message Plug-in.

SUPL subsystem makes use of the POS Message plug-in API classes to:
  • Load the POS Message Plug-in
  • Retrieve POS payload from POS Message Plug-in.
  • Forward POS messages received from the network to POS Message Plug-in.

SUPL Framework loads one and only one POS Message plug-in during initialization. There shall be one and only one POS Message plug-in installed in the system.

The following diagram shows the interaction of the SUPL subsystem with the POS Message Plug-in

Figure 1: Interaction of SUPL subsystem and POS Message Plug-in

 


Constraints

This API is valid for all platforms running on Symbian OS 9.3 or later.

 


Classification and release information

SUPL POS Message Plug-in API is available in S60 release 3.1 and onwards. This document is valid from S60 release 5.1 onwards. This is a domain/adaptation API and it is intended for licensees who want use SUPL for tunneling control plane positioning protocol messages.

 


Emulator support

This API is fully supported in the WINS/WINSCW emulator environment.

 


API description

The POS Message Plug-in implementation is an adaptation component between the SUPL Framework and the control plane positioning component. Control plane positioning protocol messages are given by the POS Message Plug-in to SUPL Framework. SUPL Framework sends the control plane positioning message as payload in SUPL POS message. SUPL Framework gives the pos payload received in SUPL POS to POS Message plug-in for further processing.

SUPL POS Message Plug-in API provides the following services to the licensee Plug-in:

POS Message Plug-in implements:
  • Methods for providing different parameters like SET Capabilities, Requested Assistance Data, Velocity and POS Payload
  • Methods for receiving parameters like Allowed Capabilities and Positioning Method, Server address
  • Methods for handling POS Payload from the network
  • Method to provide Position information to the SUPL FW for SUPL POS INIT messages.
  • Method to retrieve SUPL State information from SUPL POS Message Plug-in API.

SUPL POS Message Plug-in API is a Framework and a Method call API. It is a Framework API because POS Message Plug-in classes derive from the base classes provided by the SUPL POS Message Plug-in API.

 


Use cases

The use cases of SUPL POS Message Plug-in API are grouped as follows :

 


Get SUPL Message parameters

SUPL Framework performs the following set of operations to retrieve SUPL Message parameters from POS Message plug-in:

  • Load POS Message plug-in
  • Create a POS Session
  • Retrieve Parameters for SUPL Message (Example: SET Capabilities)
  • Destroy POS Session
  • Unload POS Handler.

 


Generate and process POS Payload

SUPL Framework performs the following set of operations to generate and process POS Payload

  • Load POS Message plug-in
  • Create POS Session
  • Post an outstanding request to POS Message plug-in for POS Payload
  • Forward POS Payload to POS Message plug-in for processing
  • Cancel the outstanding request once POS Message plug-in provides the last POS Payload
  • Destroy POS Session Unload POS Message plug-in

 


Retrieve position information from POS Message plug-in

SUPL Framework performs the following set of operations to retrieve position information from POS Message plug-in:

  • Load POS Message plug-in
  • Create a POS Session
  • Retrieve Position from POS Message plug-in
  • Destroy POS Session
  • Unload POS Handler.

 


Pass allowed capabilities from the SUPL framework to the POS Message plug-in

SUPL framework performs the following set of operations to pass the allowed capabilities as requested from the client to the POS Message Plug-in. This parameter is typically passed to the POS Plugin at the beginning of a SUPL Session.

  • Load POS Message plug-in
  • Create a POS Session
  • Pass allowed capabilities to POS Message Plug-in
  • Destroy POS Session
  • Unload POS Handler

 


Pass desired positioning method from the SUPL Framework to the POS Message Plug-in

SUPL framework performs the following set of operations to pass the positioning method as desired from the client to the POS Message Plug-in. This parameter is typically passed to the POS Plugin while a SUPL Session is in progress.

  • Load POS Message plug-in
  • Create a POS Session
  • Pass desired positioning method to POS Message Plug-in
  • Destroy POS Session
  • Unload POS Handler

 


Pass Server Address from the SUPL Framework to the POS Message Plug-in

SUPL framework performs the following set of operations to pass the positioning method as desired from the client to the POS Message Plug-in. This parameter is typically passed to the POS Plugin while a SUPL Session is in progress.

  • Load POS Message plug-in
  • Create a POS Session
  • Pass current Server Address to POS Message Plug-in
  • Destroy POS Session
  • Unload POS Handler

 


API class structure

SUPL POS Message Plug In API Class Structure
SUPL POS Message Plug-in API classes that have to be sub-classed by POS Message plug-in are COMASuplPosHandlerBase and COMASuplPosSessionBase.

COMASuplPosHandlerBase is a class that provides methods for creating POS message plug-in. The Implementation UID required for the creation of POS Message plug is provided as a parameter to NewL by the SUPL Framework. COMASuplPosHandlerBase also provides a factory method to create POS sessions. SUPL Framework is responsible for managing all the POS Sessions created by COMASuplPosHandlerBase subclass.

The important methods of COMASuplPosHandlerBase are NewL and CreateNewSessionL. NewL loads the POS Message plug-in. CreateNewSessionL creates a new POS Session to generate and handle POS Payload for a SUPL Session. POS Message plug-in allocates memory for the POS Session. SUPL Framework releases the memory allocated for POS Sessions created by invoking the destructor of the subclass of COMASuplPosSessionBase.

COMASuplPosSessionBase is the base class that must be sub-classed in order to create POS sessions. SUPL Framework creates a POS Session for every SUPL Session. The sub-class of COMASuplPosSessionBase, which is implemented by the POS Message Plug-in is responsible for processing and generating POS messages.

The important methods of COMASuplPosSessionBase are GetSuplInfoL,SetPosMethodAndAllowedCapabilities,SetCurrentServerAddress,HandleSuplPosMessageL and GetPositionLGetSuplInfoL is invoked by SUPL Framework to retrieve parameters like SET capabilities and POS Payload from POS Message plug-in. SetPosMethodAndAllowedCapabilties is invoked by SUPL Framework just before invoking GetSuplInfoL to set the Allowed capabilities and POS method required by the POS Message plug-in. HandleSuplPosMessageL is invoked by SUPL Framework to forward the POS Payload received from SLP to POS Message plug-in. GetPositionL is invoked by SUPL Framework to retrieve Position information provided if it has not received it from SLP.SetCurrentServerAddress is used by the SUPL Framework to set the server address of the server currently being used for the session in the POS Plug-in..

MOMASuplObserver is an interface that provides methods to retrieve SUPL Version and terminate the SUPL Session. POS Message Plug-in can terminate the SUPL Session in the event of unrecoverable error. SUPL Framework provides the implementation for MOMASuplObserver

 


SUPL POS Message Plug-in API data types

This section contains the details of the different data type classes that will be used to exchange information between the SUPL framework and the POS Message Plug-in.

The following diagram describes the COMASuplInfoRequest class. The other data type classes are described in the subsequent sections of this document.

Info Request List

COMASuplInfoRequestList is a container class for the different data type classes that are exchanged between SUPL framework and POS Message Plug-in. It consists of an array of COMASuplInfoRequest pointers.

COMASuplInfoRequest is the base class for all the different data types and holds information about the type of data that is exchanged between SUPL Framework and POS Message Plug-in. SUPL Framework requires data from the POS Message Plug-in for different SUPL messages. For example, to generate SUPL START, SUPL Framework requires SET Capabilities from the POS Message Plug-in. To retrieve information from the POS Message Plug-in, SUPL Framework:
  • Instantiates an object of a particular data types (Eg: COMASuplSETCapabilities)
  • Sets COMASuplInfoRequest::iType to an appropriate value (Eg: EOMASuplSETCapabilities)
  • Instantiates an object of type, COMASuplInfoRequestList Appends the COMASuplInfoRequest object pointer to COMASuplInfoRequestList::iInfoReqList.

Code example for how COMASuplInfoRequest is used by the SUPL Framework can be found in Section, Get SUPL Message parameters.

The POS Message Plug-in shall provide values for all mandatory fields [2] of the data type or return an error. If the COMASuplInfoRequest::iReqStatus is set to any value other than KErrNone, SUPL Framework does not retrieve the individual fields of the data type. Information about the mandatory parameters can be found in [2].

To retrieve multiple values, SUPL Framework creates, populates and appends multiple COMASuplInfoRequest object pointers to COMASuplInfoRequestList. If the POS Message Plug-in is unable to set the values for a particular data type in the COMASuplInfoRequestList, it shall set COMASuplInfoRequest::iReqStatus to an appropriate error code.

SET Capabilities

The diagram above describes the capabilities of the SET in terms of positioning technologies and positioning protocols.

Positioning Technology can be one or more of the following:
  • SET assisted
  • A-GPS SET based A-GPS
  • Autonomous GPS
  • AFLT (Advanced Forward Link Trilateration)
  • E-OTD (Enhanced Observed Time Difference).
Preferred modes can be one of the following:
  • SET-assisted preferred
  • SET-based preferred.
Positioning protocol can be one or more of the following:
  • RRLP (Radio Resource LCS Protocol)
  • RRC (Radio Resource Control)
  • TIA-801 (Telecommunications Industry Association - 801).

Requested Assistance Data

Requested Assistance Data is applicable for A-GPS positioning methods only. It is a bit map of the following values:
  • Almanac indicator
  • UTC model
  • Ionospheric model
  • Navigation model
  • DGPS correction
  • Reference Indication
  • Reference Time
  • Acquisition assistance
  • Real-time integrity.
POS Payload

POS Payload is wrapped in SUPL POS message. POS Payload provides the underlying RRLP, RRC or TIA-801 element to be sent in SUPL POS message

Velocity

Velocity is the optional field of SUPL POS message. Velocity field is required to overcome the lack of this information in RRLP.

Position

Position contains the position of the SET expressed in terms of position estimate along with time stamp.

SUPL Positioning Method
This enumeration allows the client of the POS Message Plugin API to inform the POS Plugin about the positioning method requested for by the SUPL Client. This is passed as a parameter in the SetPosMethodAndAllowedCapabilities() method.
Allowed Capabilities

This allows the client of the POS Message Plugin API to inform the POS Plugin about the capabilities allowed by the SUPL Client. This is done by passing an object of this class as a parameter to the SetPosMethodAndAllowedCapabilities() Method.

 


Using the SUPL Pos Message Plug-in API

To be able to provide a POS Message Plug-in the licensees shall be able to provide the implementation for the API classes defined by SUPL POS Message Plug-in API. Using the POS Message Plug-in involves the following steps :
  • Implement a subclass to COMASuplPosHandlerBase
  • Implement a subclass to COMASuplPosSessionBase
  • Provide ECom registry information for the POS Message Plug-in
  • Export an ECom style factory function at ordinal 1
  • The MMP file must specify that the module shall be built as an ECom Plug-in.

 


Implementation Details

 


Get SUPL Message Parameters

SUPL Framework retrieves parameters like SET Capabilities and Requested Assistance data from POS Message plug-in for SUPL Messages. Additionally, SUPL framework sends parameters like Allowed Capabilities and Positioning Method to the POS Plug-in for further processing.

Figure 2: Get SUPL Message parameters

The following code sample demonstrates how SUPL Framework creates instances of COMASuplInfoRequest and COMASuplInfoRequestList classes to retrieve SET Capabilities from POS Message Plug-in.

void COMASuplSessionRequestor::GetSetCapabilities()
{
    COMASuplInfoRequest *infoRequest = COMASuplSETCapabilities::NewL();
    COMASuplInfoRequestList *infoRequestList = COMASuplInfoRequestList::NewL();
    TOMASuplAllowedCapabilities  cap;
    cap.SetAllowedCapabilities(ETrue,EFalse,EFalse,EFalse,EFalse,EFalse,EFalse,EFalse);
    TOMASuplPositioningMethod posMethod = EGpsSETAssisted;
    infoRequestList->Append(infoRequest);
    SetPosMethodAndAllowedCapabilities(cap,posmethod);
    GetSuplInfo(infoRequestList, iStatus);
    SetActive();
}

The following sample code block demonstrates how the Pos Message Plug-in implements the GetSuplInfoL() Method.
EXPORT_C void COMASuplPosSession::GetSuplInfoL(COMASuplInfoRequestList *aInfoRequestList , TRequestStatus & aStatus)
{
	// Retrieve every element in the aInfoRequestList.
  TInt count = aInfoRequestList->GetCount();
  for (TInt index = 0; index < count; index ++)
  {
      	// Determine the type of the element
       COMASuplInfoRequest *reqElement = aInfoRequestList->GetElement(index);
			COMASuplInfoRequest::TOMASuplInfoType infoReqType = reqElement->Type();

       // Fill up the element with appropriate values
       switch(infoReqType)
       {
       case COMASuplInfoRequest::EOMASuplReqAsstData:
         FillUpRequestedAsstData(reqElement);
         break;
       case COMASuplInfoRequest::EOMASuplVelocity:
         FillUpVelocity(reqElement);
         break;
       case COMASuplInfoRequest::EOMASuplSETCapabilities:
          FillUpSetCapabilities(reqElement);
          break;
       case COMASuplInfoRequest::EOMASuplPosPayload:
          FillUpPosPayload(reqElement);
          break;
       case COMASuplInfoRequest::EOMASuplPosition:
          FillUpPosition(reqElement);
          break;
       default:
          reqElement->SetStatus(KErrOMASuplParamNotSet);
          break;
       }
  }
  User::RequestComplete (&aStatus,KErrNone);
}

 


Generate and Process POS Payload

When SUPL Framework is ready to send SUPL POS Message to the network, it requests the POS Message plug-in for POS payload using the GetSuplInfoL method. SUPL FW creates the data object for POS Payload (CSuplPosPayload) and performs the GetSuplInfoL request. When the POS Message plug-in has the POS Payload ready to be sent, it completes the operation with KErrNone. Once the SUPL Framework reads the POS payload, it re-posts the GetSuplInfoL request to the POS Message plug-in. When the POS message plug-in sends out the last POS payload, SUPL Framework stops posting the GetSuplInfoL request

Figure 3: Generate and Process POS Payload
The following sample code demonstrates how the Pos Message Plug-in implements the HandleSuplPosMessageL() Method.
EXPORT_C void COMASuplPosSession::HandleSuplPosMessageL(const CSuplPosPayLoad * aPosPayload)
{
	// Clone the pos payload
  // Delete any existing memory
  delete iPosPayload;
  iPosPayload = NULL;

  iPosPayload = aPosPayload->ClonePosPayloadL ()	

  // Pass the POS Paylod to the active object
  iPosProcessor->ProcessPayload(iPosPayload);

  // Return control to SUPL FW as soon as possible
}

 


Get Position

In case of Terminal Initiated Location request, Position information is provided by the SLP to SET in SUPL END message. if Position information is not present in SUPL END, SUPL Framework requests the POS Message plug-in for Position once the SUPL Session is completed. The position received from POS Message plug-in is maintained by SUPL Framework till the SUPL Session is destroyed by the SUPL Client.

Figure 4: Get Position
The following code sample demonstrates how the Pos Message Plug-in implements the GetPosition method.
EXPORT_C void COMASuplPosSession:: GetPositionL(TRequestStatus & aStatus, CSuplPosition*  aPosition)
{
	// Fill up aPosition with Position information
  TDateTime dateTime(1996,EJanuary,5,00,00,00,000000);
  TOMASuplUtcTime utcTime;
  TInt zoneCode = 0;
  TInt zone = 23;

  utcTime.SetUtcTime(dateTime, zoneCode, zone);

  TOMASuplPositionEstimate posEstimate;

  TInt latitude = 100;
  TInt longitude = 100;

  posEstimate.SetPositionEstimate(TOMASuplPositionEstimate::ENorth, latitude, longitude);

  aPosition->SetPosition(utcTime, posEstimate);
  
  // Complete User request
	User::RequestComplete (&aStatus ,KErrNone)
}
   

 


Providing Registry Information

SUPL POS Message Plug-in must provide registry information about itself. The information is stored in a registry and cannot be accessed by the user.

Registry information is provided by creating a resource file. The resource file must define a REGISTRY_INFO resource at the beginning of the file. The resource file shall not contain anything else. The REGISTRY_INFO struct and some useful constant declarations are defined in registryinfo.rh.

The registry information consists of the following:
  • SUPL POS Message Plug-in Interface UID (0x102073D4)
  • SUPL POS Message Plug-in implementation UID.
  • SUPL POS Message Plug-in version.
  • Display name for the SUPL POS Message Plug-in.
Note: The POS Message Plug-in developer must allocate two UIDs from Symbian:
  • Implementation UID
  • DLL UID.
#include <registryinfo.rh>#include "examplepos.hrh" // Defines KExamplePosImplUid

RESOURCE REGISTRY_INFO r_examplepos_reginfo
{
dll_uid = 0x10001234; 
interfaces =
    {
    INTERFACE_INFO
        {
        interface_uid = 0x102073D4;
        implementations =
            {
            IMPLEMENTATION_INFO
                {
                implementation_uid = KExamplePosImplUid;
                version_no = 2;
                display_name = "Example POS Plug-in";
                }
            };
        }
    };
}

 


Exporting a factory function

SUPL POS Message Plug-in is an ECom Plug-in and it must follow certain rules in order to be loaded by the SUPL framework. To enable loading, the POS Message Plug-in must define the following function at ordinal 1.

const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)

TImplementationProxy is defined by ECom and it contains information about the available factory functions. The POS Message Plug-in must set aTableCount to 1 and return TImplementationProxy, which points to the SUPL POS Message Plug-in factory function, i.e. NewL in the COMASuplPosProtocolHandler subclass. For more information about ECom, see reference document [3].

// Note! UID below is implementation UID, not DLL UID.
const TImplementationProxy KFactoryPtr =
    {{KExamplePosImplUid}, (TProxyNewLPtr) CExamplePosHandler::NewL};
 

EXPORT_C const TImplementationProxy* ImplementationGroupProxy(
    TInt& aTableCount)
    {
    aTableCount = 1;
    return 
    }

 


Defining the MMP file

The project file (MMP) must specify that the module is an ECom Plug-in. For more information about ECom, see reference document [3]. The second UID must be 0x10009D8D and the third UID is the POS Message Plug-in DLL UID (allocated from Symbian).

The MMP file shall at least specify \epoc32\include, \epoc32\include\oem and \epoc32\include\ecom as system includes and euser.lib and eposomasuplposmessageplugin.dll as libraries.

TARGET          examplepos.dll 
TARGETTYPE      Plug-in
UID             0x10009d8d 0x10001234

CAPABILITY      CAP_ECOM_Plug-in
SOURCEPATH      ..\src
SOURCE          OMASuplPosSession.cpp
SOURCE 				OMASUPLPosHandler.cpp
USERINCLUDE     ..\src
USERINCLUDE     ..\resource

SYSTEMINCLUDE   \Epoc32\Include
SYSTEMINCLUDE   \Epoc32\Include\oem
SYSTEMINCLUDE   \Epoc32\Include\ecom

SOURCEPATH      ..\resource

START RESOURCE  exampleresource.rss   // uid of dll
TARGET 	       examplepos.rsc
TARGETPATH      \resource
END

LIBRARY         euser.lib
LIBRARY         eposomasuplposmessageplugin.lib
The following must be followed in all POS Plug-in MMP files:
  • The target name has the file name extension DLL
  • The target type is Plug-in (see reference document [3] for details) since POS Handlers are implemented as ECom Plug-ins.
  • The second UID is 0x10009d8d to identify the DLL as an ECom Plug-in.
  • Resource file name is the same as the DLL file name.

 


Error handling

The SUPL POS Message Plug-in shall not contain any blocking calls. This is because, the POS Message Plug-in is executed in the same thread as the SUPL framework and the whole thread is blocked if there is a blocking call in the POS Message Plug-in. The suggestion is to use active objects and asynchronous calls wherever applicable.

SUPL Framework traps COMASuplPosHandlerBase::CreateNewSessionL(), COMASuplPosSessionBase::InitializeL(), COMASuplPosSessionBase::GetSuplInfoL() , COMASuplPosSessionBase::GetPositionL() and COMASuplPosSessionBase::HandleSuplPosMessageL(). POS Message Plug-in shall not leave from any other method in SUPL POS Message Plug-in API. All Symbian system leaves shall be appropriately trapped in POS Message Plug-in and the methods shall complete with appropriate Error codes.

Following tables lists the set of error codes exchanged between POS Message Plug-in and SUPL Framework. In addition to these errors, the POS Message Plug-in can return any of the standard errors defined by Symbian. The new error codes are defined in epos_omasuplposerrors.h.

Error Purpose
KErrOMASuplPosInfo SUPL Framework requests for information from POS Message using COMASuplPosSessionBase::GetSuplInfoL. If the POS Message Plug-in does not have the information requested for, POS Message Plug-in returns KErrOMASuplPosInfo. POS Message Plug-in returns KErrOMASuplPosInfo for the COMASuplPosSessionBase::GetPositionL() when the POS Message Plug-in does not have the position information.
KErrOMASuplPosInActive Soon after creation of SUPL POS Session, SUPL Framework has to invoke COMASuplPosSessionBase::InitializeL(). If SUPL Framework performs any operation before invoking COMASuplPosSessionBase::InitializeL(), then, the POS Message Plug-in will return an error code, KErrOMASuplPosInActive. Similarly, when the SUPL Framework is performing any operation after having terminated the POS Session by invoking, COMASuplPosSessionBase::SessionEnd(), POS Message Plug-in will return KErrOMASuplPosInactive.
KErrOMASuplLastPosMsg SUPL Framework requests for information from POS Message using COMASuplPosSessionBase::GetSuplInfoL. If the POS Message Plug-in does not have the more POS messages, POS Plug-in sets KErrOMASuplLastPosMsg to iReqStatus of COMASuplInfoRequest .
KErrOMASuplParamNotSet SUPL POS Message Plug-in may or may not set the optional parameters in the SUPL POS Message plug-in API data types. If SUPL Framework makes an attempt to retrieve an optional parameter that is not set by POS Message Plug-in, the Get method of the data type returns KErrOMASuplParamNetSet.

Additional errors may be defined by the SUPL POS Message plug-in API. The licensee implementation shall provide implementation for default handling so that there is no functionality break in case more errors are defined in the SUPL POS Message Plug-in API.

 


Memory overhead

SUPL POS Message Plug-in API does not add any additional memory to the SUPL Framework process. The POS Handler object and POS Session object created for every SUPL Session adds an additional memory. Objects of different data types like SET Capabilities, Velocity, Position and Requested Assistance data do not consume much memory. However, POS Payload received or generated can be big based on the underlying control plane positioning protocol. As a guideline, the licensee implementation of POS Message plug-in shall release the memory held by POS Payload after processing is complete.

 


Extensions to the API

SUPL POS Message Plug-in API can be extended by defining new classes for data types. These new classes shall not break the functionality of the existing API. The licensee implementation of the POS Message plug-in shall provide default handling for nonexistent data types so that any extension to the API does not lead to a functionality break.

 


Glossary

 


Abbreviations

Abbreviation Description
AFLT Advanced Forward Link Trilateration
API Application Programming Interface
CID Cell IDentifier
DGPS Differential Global Positioning System
DOS Domestic Operating System
E-CID Enhanced Cell IDentifiers
GSM Internet Protocol
IP SUPL Enabled Terminal
IS95 Interim Standard 95
LCS Location Services
OMA Open Mobile Alliance
OS Operating System
RRC Radio Resource Control
RRLP Radio Resource LCS Protocol
SET SUPL Enabled Terminal
SLP SUPL Location Platform
SMS Short Messaging Service
TIA Telecommunications Industry Association, standardization body in the United States
UTC Coordinated Universal Time
WAP Wireless Application Protocol

 


Definitions

Definition Description
Allowed Capabilities These are the positioning capabilities set by the SUPL Client.
Control Plane The control plane oversees the operation of the data plane, allocating resources, providing information, and handling errors to allow data plane operations to be continuous and efficient.
ECom A system support that allows the loading of interface implementations
MMP file A project definition file. Specifies the properties of a project in a platform and compiler independent way.
POS Module The licensee component that interacts with SUPL Framework as well as control plane positioning protocol that resides in the Domestic Operating System
Positioning Method The type of positioning desired by the SUPL Client
SUPL Subsystem S60 subsystems that handles exchange of SUPL messages between the hand set and the network
Network Initiated Location Request A Location Request that originates in the network
Terminal Initiated Location Request A Location Request that originates in the SET
SUPL Enabled Terminal (SET) A device that is capable of communicating with a SUPL network. Examples of this could be Mobile Terminal in GSM or IS95.
SUPL Location Platform (SLP) Entity responsible for Service management and Position determination. SUPL Location Platform contains the SUPL Location Center and SUPL Positioning Center functions.
UID Unique Identifier number in Symbian OS.
User plane Packet or Circuit Switched Data Channels

 


References

1. OMA-AD-SUPL-V1_0 SUPL Architecture Description by OMA http://member.openmobilealliance.org/
2. OMA-TS-ULP-V1 SUPL Technical Specification by OMA http://member.openmobilealliance.org/
3. Plug-in Architecture 6.2 – ECom Architecture Overview http://www.symbian.com/
4. S60 Location Acquisition API Specification  
5. S60 SUPL Subsystem Design Document  
6. S60 SUPL Terminal Initiation API Specification  
7. S60 SUPL Network Initiation API Specification  

Back to top