S60 SUPL Network Initiation API |
DN0623643 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
2.0 |
24.11.2006 |
Approved |
Changes for dynamic variation of the SUPL feature. |
1.0 |
23.03.2006 |
Approved |
|
![]() |
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.
![]() |
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.
![]() |
The main use case of SUPL Network Initiation API is as follows:
All methods in SUPL Network Initiation API are synchronous calls.
![]() |
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.
![]() |
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:
It is recommended that the client should close the connection to SUPL Server when it is no longer required.
![]() |
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.
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
![]() |
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.
![]() |
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.
![]() |
![]() |
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 |
![]() |
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. |
![]() |
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/ |
![]() |