S60 SUPL Network Initiation API

DN0623643
CONFIDENTIAL

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

2.0

24.11.2006

Approved

Changes for dynamic variation of the SUPL feature.

1.0

23.03.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API description
Use cases
API class structure
Using SUPL Network Initiation API
Forwarding SUPL initiation message to SUPL Server
Error handling
Memory overhead
Glossary
Abbreviations
Definitions
References

 


Purpose

Secure User Plane Location (SUPL) defines how the location related information is transferred and how already existing control plane positioning protocols can be tunneled over the user plane between terminal and network server. The network sends SUPL initiation message to the terminal to start the SUPL Session either as SMS or as WAP push message. The purpose of SUPL Network Initiation API is to enable client running in the terminal to forward these SUPL initiation messages received from the network to the SUPL server. SUPL Network Initiation API is valid for S60 release 3.1 and onwards.

 


S60 or Symbian OS exceptions

SUPL Network Initiation API is valid for S60 release 3.1 and onwards.

 


API description

The client uses SUPL Network Initiation API to forward the SUPL initiation messages received from the network.

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

The only class of SUPL Network Initiation API is server class. The server class is used by client applications for connecting to SUPL server, to forward message to SUPL server and to close connection to SUPL server.

 


Use cases

The main use case of SUPL Network Initiation API is as follows:

  • Forwarding SUPL initiation message to SUPL server

All methods in SUPL Network Initiation API are synchronous calls.

 


API class structure

The only class of SUPL Network Initiation API is RSuplNetworkServer. RSuplNetworkServer is used to establish connection and to close the connection to SUPL Server and to forward message received from the network 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 error and exits.

Following diagram presents the class hierarchy and methods in RSuplNetworkServer.

Figure 1: Client-server communication classes

 


Using SUPL Network Initiation API

Client application using SUPL Network Initiation API must have CommDD capability to use all methods.

Using SUPL Network Initiation API always contains the following steps:

  1. Connect to SUPL Server using the RSuplNetworkServer::Connect() method.
  2. Forward message using the RSuplNetworkServer::ForwardMessage method.
  3. Close connection using the RSuplNetworkServer::Close() method.

It is recommended that the client should close the connection to SUPL Server when it is no longer required.

 


Forwarding SUPL initiation message to SUPL Server

SUPL Network Initiation client establishes a connection to SUPL Server before forwarding SUPL initiation message. After forwarding message is completed, the client can close the connection to SUPL Server.

The following diagram illustrates the steps involved in forwarding a message using SUPL Network Initiation API.

Figure 2: Forwarding a message to SUPL Server

The following code snippets illustrates how to forward the message to SUPL Server.

RSuplNetworkServer	server;
    
TInt ret = server.Connect();   // Connect to server
if (ret != KErrNone)
  {
  	// Handle error
  }

//Create dummy string to pass as parameter
_LIT8(KConstStr, "ForwardMessage test message");
// Forward message to SUPL server
ret = server.ForwardMessage(KConstStr);
if (ret != KErrNone)
	{
  // Handler error
  }

server.Close();			// Close connection

 


Error handling

SUPL Network Initiation API uses the standard Symbian error reporting mechanism. In case of an irrecoverable error, panics are used. Otherwise, functions return error codes as their return values. SUPL Network Initiation API uses standard system error codes and certain panic codes defined in SUPL Network Initiation API. These can be found in the epos_suplnetworkerrors.h file.

 


Memory overhead

When using SUPL Network 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. In all cases the amount of memory is defined by the client and thus cannot be exactly predicted. The number of simultaneous connections also has an impact on the overall memory usage. For this reason, unnecessary connections should be avoided.

 


Glossary

 


Abbreviations

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

 


Definitions

Table: Definitions
Definition Description
Framework Usually denotes the collection of an engine and associated programming interfaces. This document mentions the SUPL Framework.
Network Initiated Location Request A Location request that originates in the network
SUPL Enabled Terminal (SET) 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 SUPL Subsystem Architecture Description  
2. S60 SUPL Subsystem Design Document  
3. S60 SUPL Network Initiation Library Design Document  
4. OMA Secure User Plane Location Architecture http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/
5. OMA UserPlane Location Protocol http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/

Back to top