SUPL Network Initiation API

Changes in SUPL Network Initiation API

2.0 24.11.2006 Approved Changes for dynamic variation of the SUPL feature.

1.0

23.03.2006

Approved

Changes in SUPL Network Initiation API

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.

Constraints

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.

Client-server communication classes


Client-server communication classes

Related APIs
  • RSuplNetworkServer

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:

  • Connect to SUPL Server using the RSuplNetworkServer::Connect() method.

  • Forward message using the RSuplNetworkServer::ForwardMessage method.

  • 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.

Forwarding a message to SUPL Server


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 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.

Related APIs
  • RSuplNetworkServer::Close()
  • RSuplNetworkServer::Connect()
  • RSuplNetworkServer::ForwardMessage

Glossary

Abbreviations

Abbreviations

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

Definitions

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

References

1. SUPL Subsystem Architecture Description

2. SUPL Subsystem Design Document

3. 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/