S60 5.1 SUPL POS Message Plug-in API Specification |
DN0999999 |
CONFIDENTIAL |
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. |
![]() |
The following header file(s) have changed between S60 releases 3.1 and 5.1
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. |
![]() |
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 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
![]() |
![]() |
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.
![]() |
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:
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.
![]() |
The use cases of SUPL POS Message Plug-in API are grouped as follows :
![]() |
SUPL Framework performs the following set of operations to retrieve SUPL Message parameters from POS Message plug-in:
![]() |
SUPL Framework performs the following set of operations to generate and process POS Payload
![]() |
SUPL Framework performs the following set of operations to retrieve position information from 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.
![]() |
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.
![]() |
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.
![]() |
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
![]() |
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.
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
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 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.
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.
![]() |
![]() |
![]() |
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.
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(); }
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); }
![]() |
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
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 }
![]() |
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.
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) }
![]() |
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.
#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"; } }; } }; }
![]() |
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 }
![]() |
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 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.
![]() |
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.
![]() |
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.
![]() |
![]() |
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 |
![]() |
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 |
![]() |
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 |
![]() |