S60 SUPL Terminal Initiation API

DN0623655
CONFIDENTIAL

©Nokia Corporation and/or its subsidiaries 2006-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

4.0

05.10.2007

Approved

Added changes to indicate whether the RunSession() request is the first one or not in the subsession.

3.0

24.11.2006

Approved

Changes for dynamic variation of SUPL feature flag.

2.0

02.06.2006

Approved

Changes to add new indication code

1.0

23.03.2006

Approved

 


Table of Contents

Changes
Purpose
S60 or Symbian OS exceptions
Emulator support
API description
Use cases
API class structure
Using SUPL Terminal Initiation API
Requesting position information
Multiple position information requests
Requesting assistance data
Canceling a position determination request
Requesting position information from specific server
Error handling
Memory overhead
Glossary
Abbreviations
Definitions
References

 


Changes

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

Table: epos_suplterminal.h
Type Class Change
New public methods RSuplTerminalSubSession TInt GetSlpList(RPointerArray(CSuplTerminalParams) &aSlpList)
New public method RSuplTerminalSubSession RunSession(TRequestStatus& aStatus, TSuplTerminalQop& aQop, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue)
New public method RSuplTerminalSubSession TInt RunSession(TSuplTerminalQop& aQop, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue)
New public method RSuplTerminalSubSession RunSession(TRequestStatus& aStatus, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue)
New public method RSuplTerminalSubSession TInt RunSession(const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue)
New public method RSuplTerminalSubSession TInt GetServerAddress(TDes& aHslpAddress)
Table: epos_suplterminalparams.h (new file)
Type Class Change
New public method CSuplTerminalParams TInt Set()
New public method CSuplTerminalParams TInt Get()

 


Purpose

Secure User Plane Location (SUPL) protocol defines how location related information is transferred and how the existing control plane positioning protocols can be tunneled over the user plane between terminal and network server. The main purposes of SUPL Terminal Initiation API are:
  • To enable terminal client to determine terminal's position information using SUPL protocol and retrieve it.
  • To enable terminal client to retrieve additional positioning information such as assistance data for A-GPS using SUPL protocol.
  • To retrieve configured server addresses and their properties

 


S60 or Symbian OS exceptions

SUPL Terminal Initiation API is valid from S60 release 3.1 onwards. This API specification is valid for S60 5.1 onwards.

 


Emulator support

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

 


API description

The terminal client uses SUPL Terminal Initiation API for following purposes:
  • To determine location information and to retrieve the location information optionally with desired quality of position.
  • To retrieve additional positioning information such as assistance data for A-GPS for tunneled positioning protocols. In this case, assistance data is delivered to the client's plug-in from the SUPL framework during SUPL session.
  • To retreive configured server addresses and their properties

SUPL Terminal Initiation API is a Virtual Machine API abstracting the client-server communication from the client. SUPL Terminal Initiation API belongs to the Domain API category.

SUPL Terminal Initiation API is dependent on Location Acquisition API for location data types. However, the methods in SUPL Terminal Initiation API can also return extended position information, such as speed, using extended position information defined by Location Acquisition API.

 


Use cases

The main use cases of SUPL Terminal Initiation API are as follows:

  • Requesting position information
  • Multiple position information requests
  • Requesting Assistance Data
  • Cancelling position determination request
  • Retrieving configured server properties

 


API class structure

The important classes of SUPL Terminal Initiation API are RSuplTerminalServer, RSuplTerminalSubSession, CSuplTerminalParams and TSuplTerminalQop. RSuplTerminalServer is used to establish connection and close the connection to SUPL Server. During connection establishment, SUPL Server checks whether SUPL is enabled or not in the terminal. If SUPL is not enabled, SUPL Server returns an error code and exits. If SUPL is enabled, connection establishment continues.RSuplTerminalSubSession is used to
  • open and close IPC sub-session
  • request SUPL Server to determine the position information and retrieve the position information
  • request SUPL Server for assistance data for A-GPS
  • cancel position determination request
  • retrieve all configured servers and their properties

The important methods in RSuplTerminalSubSession are RunSession() and GetPosition(). RunSession() is used for requesting SUPL Server to determine position information. This method is provided in both synchronous and asynchronous variants.

Client can specify the wanted quality of the fix by giving the TSuplTerminalQop class as parameter for RunSession(). The quality of position includes horizontal accuracy, vertical accuracy, maximum location age and response time. Horizontal accuracy is the radius of the error estimate circle specified in meters. Horizontal accuracy reflects the error for the latitude and longitude components of a position. Vertical accuracy is the error in the altitude component. Vertical accuracy specifies a linear value at a vertical distance from the origin of the error estimate circle within which the location of the point falls. Both horizontal accuracy and vertical accuracy values are specified in meters. Maximum location age is the maximum tolerable age of position estimates used for cached position fixes. Delay time is the desired response time for the location request issued. Maximum location age and delay are specified in seconds.

Parameter aSETCaps of type TInt is used for restricting the positioning technologies available for determining position information. This indicates the position technologies available which can be used during position determination. For example when using SUPL Server for retrieving assistance data this parameter is set to KGpsSETBased. Parameter aRequestId of type TInt can be used by the client to deliver request identification number for the tunneled positioning protocol handler. This is used by the client which is requesting for additional position information such as assistance data for A-GPS. It is the client's responsibility to generate and keep track of this request identifier. Tunneled protocol can use this value for example to match different assistance data requests and response received from SUPL Server.

Parameter aFirstReq of type TBool is used to indicate whether the request is the first request in the subsession or not. For example when making a location request or assistance data request for the first time in the subsession this parameter is set to ETrue. For subsequent requests this parameter is set to EFlase.

Parameter aHslpAddress of type String is used to specify SUPL server to be used during SUPL session.

Parameter aFallBack of type TBool is used to indicate whether fallback is allowed to next server in the SLP list if SUPL session with the server mentioned fails.

GetPosition as indicated is used to retrieve the position information from SUPL Server. The client requesting for assistance data for tunneled protocol does not need to use this method as assistance data is delivered during SUPL session. The method can return a variation of position values, such as basic position information and extended position information.

GetServerAddress can be used to retrieve the address of the server used in the last SUPL session.

Client can retrieve all the configured servers and their properties using CSuplTerminalParams class as parameter for GetSlpList(). From the retrieved server properties client can use the server address field as parameter for RunSession() to indicate which server should be used for SUPL session. Client can also specify whether fallback can be used or not if SUPL session with the specified server fails.

All methods in SUPL Terminal Initiation API are synchronous calls, except for asynchronous method requesting SUPL Server to determine position information.

The following diagram presents the class hierarchy and methods in both RSuplTerminalServer and RSuplTerminalSubSession.

Figure 1: Client-server communication classes

 


Using SUPL Terminal Initiation API

The client application using SUPL Terminal Initiation API must have the CommDD capability to use all methods.

Using SUPL Terminal Initiation API always contains the following steps:

  1. Connect to SUPL server using the RSuplTerminalServer::Connect() method.
  2. Open a subsession to SUPL Server using the RSuplTerminalSubSession::Open() method.
  3. Optionally client can retrieve all the configured server address and their properties using RSuplTerminalSubSession::GetSlpList()
  4. Determine the position information or get additional position information such as assistance data for A-GPS using the RSuplTerminalSubSession::RunSession() method. The RunSession() method is available both in synchronous and asynchronous variants. The client can also optionally specify the desired Quality of Position (QoP), server address to be used and whether fallback can be used or not.
  5. Optionally get terminal's determined location information using the RSuplTerminalSubSession::GetPosition() method.
  6. Optionally get server used for SUPL session using the RSuplTerminalSubSession::GetServerAddress() method.
  7. Close subsession using the RSuplTerminalSubSession::Close() method.
  8. Close connection using the RSuplTerminalServer::Close() method.

RSuplTerminalSubSession::CanceRunSession() can be used to cancel an outstanding asynchronous RSuplTerminalSubSession::RunSession() request.

In case of asynchronous calls, the TRequestStatus parameter variable is used to indicate when SUPL Server has finished processing the request. For one IPC subsession, there can be only one request outstanding on each asynchronous method. It is recommended that the client should close the subsession and connection to SUPL Server when it is no longer required.

 


Requesting position information

This use case describes about the procedure to make the location determination request using SUPL and retrieving the position determined using SUPL Terminal Initiation API.

The following diagram illustrates the steps involved in executing the use case.

Figure 2: Requesting position information

The following code snippets illustrate how to make the position determination request and how to retrieve position information using TPositionInfo. Asynchronous method is used to determine the position information here.

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
TInt requestId = 1;
TSuplTerminalQop qop;

// Set desired quality of position
ret = qop.Set(100, 990, 100, 8);
// Make asynchronous position determination request
subSession.RunSession(status, qop, setCaps, requestId);
User::WaitForRequest(status);
if (status.Int() != KErrNone)
	{
  // Handler error
  }

TPositionInfo posInfo;
//Retrieve determined position information
ret = subSession.GetPosition(posInfo);
if (ret != KErrNone)
	{
  // Handle error
  }

subSession.Close();			// Close sub-session
server.Close();			// Close connection

The following code snippets illustrate how to use the make position determination request and how to retrieve position information using HPositionGenericInfo. An asynchronous method is used to determine the position information here. For more information on how to use HPositionGenericInfo, please refer to reference document [3].

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
TInt requestId = 1;
TSuplTerminalQop qop;

// Set desired quality of position
ret = qop.Set(100, 990, 100, 8);
// Make asynchronous position determination request
subSession.RunSession(status, qop, setCaps, requestId);

User::WaitForRequest(status);
if (status.Int() != KErrNone)
	{
  // Handle error
  }

HPositionGenericInfo* genericInfo = HPositionGenericInfo::NewLC();
//Request for Horizontal speed and Horizontal speed error
genericInfo->SetRequestedField(EPositionFieldHorizontalSpeed);
genericInfo->SetRequestedField(EPositionFieldHorizontalSpeedError);

//Retrieve determined position information
ret = subSession.GetPosition(*genericInfo);
if (ret != KErrNone)
	{
  // Handle error
	}
// Check if requested field is returned or not
if (genericInfo->IsFieldAvailable(EPositionFieldHorizontalSpeed))
  {
  TInt16 HorSpeed;
  genericInfo->GetValue(EPositionFieldHorizontalSpeed, HorSpeed);
  }
if (genericInfo->IsFieldAvailable(EPositionFieldHorizontalSpeedError))
  {
  TInt8 speedError;
  genericInfo->GetValue(EPositionFieldHorizontalSpeedError, speedError);
  }
CleanupStack::PopAndDestroy(genericInfo); //genericInfo
subSession.Close();			// Close sub-session
server.Close();			// Close connection

 


Multiple position information requests

This use case describes the procedure to make the multiple location determination requests using SUPL and retrieving the position determined using SUPL Terminal Initiation API. Optionally client can specify whether the location request made is the first request in the sub-session or not.

The following diagram illustrates the steps involved in executing the use case.

Figure 3: Multiple position information requests

The following code snippets illustrate how to make the multiple position determination request and how to retrieve position information using TPositionInfo. An asynchronous method is used to determine the position information here.

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
TInt requestId = 1;
TSuplTerminalQop qop;

// Set desired quality of position
ret = qop.Set(100, 990, 100, 8);
// Make asynchronous position determination request
subSession.RunSession(status, qop, setCaps, requestId);
User::WaitForRequest(status);
if (status.Int() != KErrNone)
	{
  // Handler error
  }

TPositionInfo posInfo;
//Retrieve determined position information
ret = subSession.GetPosition(posInfo);
if (ret != KErrNone)
	{
  // Handle error
  }

status = KErrNone;
// Make asynchronous position determination request
subSession.RunSession(status, qop, setCaps, requestId, EFalse);
User::WaitForRequest(status);
if (status.Int() != KErrNone)
	{
  // Handle error
  }

TPositionInfo posInfo;
//Retrieve determined position information
ret = subSession.GetPosition(posInfo);
if (ret != KErrNone)
	{
  // Handle error
  }

subSession.Close();			// Close sub-session
server.Close();			// Close connection

 


Requesting assistance data

This use case describes the procedure to make assistance data request using SUPL Terminal Initiation API. Assistance data is delivered tunneled in SUPL protocol and the tunneled protocol handler receives assistance data for position determination. In this case, the client receives assistance data during SUPL session. For this reason the client does not need to call GetPosition to get position information.

The following diagram illustrates the steps involved in requesting assistance data using SUPL Terminal Initiation API.

Figure 4: Requesting assistance data

The following code snippets illustrate how to use the make assistance data request. An asynchronous method is used to make the assistance data request.

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
// Make asynchronous position determination request
subSession.RunSession(setCaps, status);
User::WaitForRequest(status);
if (status.Int() != KErrNone)
	{
  // Handle error
  }
subSession.Close();			// Close sub-session
server.Close();			// Close connection

 


Canceling a position determination request

This use case describes the procedure to make the asynchronous position determination request using SUPL Terminal Initiation API and cancelling the position determination request.

The following diagram illustrates the steps involved in executing the use case.

Figure 5: Canceling a position determination request

The following code snippets illustrate how to use the make position determination request using an asynchronous method and how to cancel the request.

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
// Make asynchronous position determination request
subSession.RunSession(setCaps, status);
subSession.CancelRunSession();
User::WaitForRequest(status);
if (ret != KErrCancel)
	{
  // Handle error
  }
subSession.Close();			// Close sub-session
server.Close();			// Close connection

 


Requesting position information from specific server

This use case describes following
  • To retrieve configured servers and their properties
  • To make the location determination request using SUPL to particular server with fallback enabled
  • Retrieving server address that was used for position determination
  • Retrieving the position determined using SUPL Terminal Initiation API

The following diagram illustrates the steps involved in executing the use case.

Figure 6: Requesting position information from specific server

The following code snippets illustrate how to use the make position determination request using an asynchronous method and how to cancel the request.

RSuplTerminalServer	server;
RSuplTerminalSubSession subSession;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }
ret = subSession.Open(server);			// Open sub-session to server
if (ret != KErrNone)
  {
  	// Handle error
  }
// Get list of SLPs configured and retrieve parameters
RPointerArray<CServerParams> aParamValues;
HBufC* serverAddress = HBufC::New(255);
HBufC* iapName = HBufC::New(255);
TBool serverEnabled;
TBool simChangeRemove;
TBool usageInHomeNw;
TBool editable;
subSession.GetSlpList(aParamValues);
// Retrieve first server properties in the list
aParamValues[0]->Get(slpId,serverAddress->Des(),iapName->Des(),serverEnabled,simChangeRemove,usageInHomeNw,editable);

// Set terminal capabilities
TInt 	setCaps=EGpsSETAssisted|EGpsSETBased;
TRequestStatus status = KErrNone;
// Make asynchronous position determination request
TBool fallBack = ETrue;
subSession.RunSession(status, *serverAddress, fallBack, setCaps);
User::WaitForRequest(status);
if (ret != KErrCancel)
	{
  // Handle error
  }
aParamValues.ResetAndDestroy();
// Retrieve server address used for SUPL session
RBuf hslpAddr;
RBuf hslpAddr.Create(KMaxHslpAddressLength);
subSession.GetServerAddress(hslpAddr)
hslpAddr.Close();

subSession.Close();			// Close sub-session
server.Close();			// Close connection

 


Error handling

SUPL Terminal Initiation API uses the standard Symbian OS error reporting mechanism. In case of an irrecoverable error, panics are used. Otherwise, functions return error codes as their return values. SUPL Terminal Initiation API uses standard system error codes and certain panic codes defined in SUPL Terminal Initiation API. Those can be found in the files epos_suplterminalerrors.h and epos_suplterminalconstants.h.

 


Memory overhead

When using SUPL Terminal Initiation API, the memory overhead is dependent on the amount of instantiated classes but there are also some cases when extra memory usage can be involved. Nevertheless, the memory usage is always controlled by the client application and there are never any uncontrolled allocations of large amounts of memory that the client cannot prevent or avoid. Also the HPositionGenericInfo class uses a heap to store location data. However, in all cases, the amount of memory is defined by the client and thus cannot be exactly predicted. After use, the needed additional buffers (if any) are unallocated automatically. The number of simultaneous sessions and subsessions also has an impact on the overall memory usage. For this reason, unnecessary sessions and subsessions should be avoided.

 


Glossary

 


Abbreviations

Table: Abbreviations
Abbreviation Description
API Application Programming Interface
FW Framework
HW Hardware
IPC Inter process communication
QoP Quality of Position
SET SUPL Enabled Terminal
SLP SUPL Location Platform
SUPL Secure User Plane Location Protocol
UI User Interface

 


Definitions

Table: Definitions
Definition Description
Framework Usually denotes the collection of an engine and associated programming interfaces. This document mentions SUPL Framework.
Terminal Initiated Location Request Location request is issued by the mobile terminal to find out current location of the terminal.
SUPL Enabled Terminal A device that is capable of communicating with a SUPL Network. Examples of this could be UE in UMTS, MS in GSM or IS95.
SUPL Location Platform (SLP) Network entity responsible for Service management and Position determination.
SUPL Server Server application running in the terminal.

 


References

Table: References
1. S60 3.2 SUPL Subsystem Architecture Description  
2. S60 SUPL Subsystem Design Document  
3. S60 SUPL Terminal Initiation Library Design Document  
4. S60 Location Acquisition API Specification Document  
5. OMA Secure User Plane Location Architecture http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/
6. OMA UserPlane Location Protocol http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/

Back to top