<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E" xml:lang="en"><title>SUPL

Push API</title><shortdesc>The SUPL Push API is used to process <codeph>SUPL INIT</codeph> messages

sent from a SUPL Location Platform (SLP). </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Note: From Symbian^3 the SUPL Protocol Module is deprecated.

For the preferred way of using SUPL see <xref href="GUID-1F7F543A-8A9C-4460-BDB1-A6866E9DF0B9.dita">SUPL

Proxy Protocol Module</xref>. </p>

<section id="GUID-E41670FA-DE7E-44F2-8664-9124B2D75A61"><title>Purpose</title> <p>This document describes the SUPL Push API

which is used to process <codeph/><codeph>SUPL INIT</codeph> messages

sent from a SUPL Location Platform (SLP). A <codeph>SUPL INIT</codeph> message

is sent from an SLP to a SUPL Enabled Terminal (SET) to start a network initiated

location request. </p> <p><xref href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita">SUPL

Protocol Module Overview</xref> describes how the WAP Push plug-in and test

SMS Trigger plug-in use the SUPL Push API to forward <codeph>SUPL INIT</codeph> messages

to the SUPL Protocol Module (SPM). </p> <p>This document is intended for Symbian

licensees who want to create their own handlers to process <codeph>SUPL INIT</codeph> messages.

Licensees who simply want to use the WAP Push plug-in do not need to use this

API. </p> </section>

<section id="GUID-8C01FD97-A1A2-4618-AD92-CB4D7E3F93C5"><title>Introduction</title> <p>Secure User Plane Location (SUPL)

is a standard for enabling Location Based Services using IP for most of the

communication between a SET and an SLP. To start a network initiated request,

the SLP must send a <codeph>SUPL           INIT</codeph> message to a SET.

The flow of events is as follows: </p> <ol id="GUID-221892B8-4886-555C-9FCB-C32B90F636AD">

<li id="GUID-B99B0CE0-8C5A-5F89-8310-A46A3398387D"><p>To start a location

request, the SLP sends a <codeph>SUPL INIT</codeph> message to the SET using

WAP Push or SMS Trigger [<xref href="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita#GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E/GUID-202D83AC-6C99-5481-8074-ACFEBD426AE3">1</xref>]. </p> </li>

<li id="GUID-85ADC9EF-AE10-5F69-87F6-4DDE307DDBD2"><p>To support SUPL, the

LBS subsystem ROM is built to include the SUPL WAP Push plug-in or an SMS

Trigger plug-in as described in <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL

Protocol Module Quick Start</xref>. </p> <p>The <codeph>SUPL INIT</codeph> message

is received by either the WAP Push plug-in (loaded by the WAP Push Framework)

or the SMS Trigger plug-in (loaded by the Messaging Watcher Framework) shown

in figure 1. Either plug-in processes a <codeph>SUPL INIT</codeph> message

and call the methods of the SUPL Push API to cause the SUPL Protocol Module

to open a socket connection to the SLP. </p> <p>A licensee can also create

their own <codeph>SUPL INIT</codeph> handler to process messages received

from an SLP. All <codeph>SUPL INIT</codeph> handlers must use the SUPL Push

API. </p> </li>

<li id="GUID-5B15D26D-5FD8-5421-8A41-5100C67F316A"><p>The SLP and the SET

process the location request as described in <xref href="GUID-DC0F9E05-CB03-5BA6-AA5F-7D9A83070FAF.dita">SUPL

sequence diagrams</xref>. </p> </li>

</ol> </section>

<section id="GUID-4C059230-5393-4AEA-8A77-A4852260EE11"><title>Symbian plug-ins that use the SUPL Push API</title> <p>Symbian

provides two plug-ins that can process <codeph>SUPL INIT</codeph> messages

and call the SUPL Push API: </p> <ul>

<li id="GUID-DB057171-D10D-5C53-8B0A-CCB150AB1184"><p>The SUPL WAP Push plug-in

receives <codeph>SUPL INIT</codeph> messages sent via WAP Push. </p> </li>

<li id="GUID-B39D8B6C-D679-57E0-99D6-903B1EF4899D"><p>The Symbian test SUPL

SMS Trigger plug-in receives <codeph>SUPL                 INIT</codeph> messages

sent via SMS. </p> </li>

</ul> <p>The SUPL WAP Push handler plug-in and SUPL SMS Trigger plug-in use

the SUPL Push API to notify the SUPL Protocol Module that an SLP is starting

a network initiated location request. </p> <fig id="GUID-BEDFACD2-D262-500C-ACF5-37679F7FA091">

<title>              Figure 1: SUPL Push API and Symbian plug-ins        

   </title>

</fig> <p><b>SUPL

WAP Push plug-in</b> </p> <p>The Symbian platform includes the WAP Push Framework

to process WAP Push messages. If the Symbian SUPL WAP Push plug-in is installed,

the WAP Push Framework uses it to process <codeph>SUPL INIT</codeph> messages

sent by WAP Push. The plug-in calls the methods of the SUPL Push API causing

the SUPL Protocol Module to open a connection to the SLP. </p> <p>The SUPL

WAP Push handler plug-in is a production component. Licensees can install

the plug-in in their ROM so that it is available to the WAP Push Framework.

Licensees do not need to develop their own WAP Push handler plug-in. See <xref href="GUID-91F95D0C-E4CF-510E-B280-E27F89274ACE.dita">SUPL Protocol Module Quick

Start</xref> for details of how to configure an LBS ROM to include the WAP

Push plug-in. </p> <p>Source code for the WAP Push plug-in can be found at <filepath>&lt;LBS_SOURCE_ROOT&gt;/LbsSuplProtocolModule/SuplWapPush</filepath> and consists of a single class which gets the <codeph>SUPL INIT</codeph> message

body and uses the SUPL Push API to forward it to the SUPL Protocol Module. </p> <p><b>SUPL SMS Trigger plug-in</b> </p> <p>If the Symbian SUPL SMS Trigger plug-in

is installed, it is loaded on OS startup by the Watcher Framework, which uses

it to process <codeph>SUPL              INIT</codeph> messages sent by SMS

Trigger. The plug-in calls the methods of the SUPL Push API causing the SUPL

Protocol Module to open a connection to the SLP. </p> <p>Source code for the

SMS Trigger plug-in can be found at <filepath>&lt;LBS_SOURCE_ROOT&gt;/LbsSuplProtocolModule/SuplSmsTrigger</filepath> and

consists of a single class which gets the <codeph>SUPL INIT</codeph> message

body and uses the SUPL Push API to forward it to the SUPL Protocol Module. </p> </section>

<section id="GUID-B7FCA0ED-7ADE-46D0-AC7A-29ED26805FB4"><title>SUPL Push API description</title> <p>The SUPL Push API is

used to notify the SUPL Protocol Module that a SUPL INIT message was received

from an SLP to start a network location request. </p> <p>The SUPL API has

two different types of client: </p> <ul>

<li id="GUID-E14E2A80-5E87-558C-BF90-9EF8685DCF90"><p>Clients that receive <codeph>SUPL

INIT</codeph> messages and send them into the LBS subsystem, such as the Symbian

WAP Push plug-in. These components use the SUPL Push API sender classes. </p> </li>

<li id="GUID-3327FFF2-F626-5679-9CA4-9769B0862380"><p>Clients that require

notification of <codeph>SUPL INIT</codeph> messages, such as the SUPL Protocol

Module. The SUPL Protocol Module uses the SUPL Push API receiver classes to

receive notification of network initiated location requests. </p> </li>

</ul> <p>The SUPL Push API has <codeph>publishedPartner</codeph> interface

access. </p> <p><b>SUPL

Push API sender classes</b> </p> <p>This section describes the classes of

the SUPL Push API that the SUPL WAP Push handler plug-in and SUPL SMS Trigger

plug-in use to send <codeph>SUPL              INIT</codeph> messages into

the LBS subsystem. Figure 2 shows the SUPL Push API sender classes. Licensees

use the API sender classes to implement their own <codeph>SUPL INIT</codeph> handler

(if required). </p> <fig id="GUID-47957CAE-DC5F-55C9-B157-6274D00B0990">

<title>                 Figure 2: Class diagram of SUPL Push API sender classes

              </title>

</fig> <table id="GUID-01E93B41-A2AB-5251-947D-E4839A0AC71D">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Class name</entry>

<entry>Description</entry>

<entry>Header file</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita"><apiname>CLbsSuplPush</apiname></xref>  </p> </entry>

<entry><p>The interface used to send <codeph>SUPL INIT</codeph> messages to

the LBS subsystem. A WAP Push message handler or SMS Trigger handler creates

and owns an instance of this class. The class defines the interface only and

delegates all its functionality to an implementation class. </p> </entry>

<entry><p> <filepath>lbssuplpush.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7A1E29E6-CF2C-3B19-BADE-2DDD67F6DC36.dita"><apiname>MLbsSuplPushObserver</apiname></xref>  </p> </entry>

<entry><p>The observer interface used with <codeph>CLbsSuplPush</codeph>.

The interface defines a callback method to allow message delivery results

to be returned to a client. The Symbian WAP Push plug-in implements this interface

to receive confirmation of <codeph>SUPL INIT</codeph> message delivery to

the SUPL Protocol Module. </p> </entry>

<entry><p> <filepath>lbssuplpush.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-EDDB3400-9EBC-3518-8047-D49C4A261C08.dita"><apiname>_TLbsSuplPushChannel</apiname></xref> and <xref href="GUID-C6EB9DF6-1AAF-3754-9F55-6CC5373EDB61.dita"><apiname>TLbsSuplPushChannel</apiname></xref>  </p> </entry>

<entry><p>Defines an enumeration and a typedef for the source of the <codeph>SUPL

INIT</codeph> message. Two 'channels' are defined: a WAP push channel and

an SMS trigger channel. </p> </entry>

<entry><p> <filepath>lbssuplcommon.h</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Request queueing </b> </p> <p>The SUPL Push API uses Publish and Subscribe

(P&amp;S) properties to store the details of <codeph>SUPL INIT</codeph> messages.

Properties are written by SUPL Push API sender class clients and are read

by SUPL Push API receiver class clients. </p> <p>One potential problem with

using P&amp;S properties occurs in the situation where multiple calls to <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita#GUID-A55B3609-097F-3D14-80FF-76ADA5462621/GUID-5AD5A31B-0DE0-36DF-A19F-E0E57EBCCEA9"><apiname>CLbsSuplPush::SuplInit()</apiname></xref> are

made in quick succession. Without a means of queueing requests and synchronising

access to P&S properties, it would be possible for property values to

be overwritten without first being read, leading to the possible loss of some <codeph>SUPL

INIT</codeph> messages. </p> <p>The implementation of the SUPL Push API queues <codeph>SUPL

INIT</codeph> messages that are sent by API clients by calling <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita#GUID-A55B3609-097F-3D14-80FF-76ADA5462621/GUID-5AD5A31B-0DE0-36DF-A19F-E0E57EBCCEA9"><apiname>CLbsSuplPush::SuplInit()</apiname></xref> and

also synchronises access to the P&amp;S properties so that all received <codeph>SUPL

INIT</codeph> messages are processed by the SUPL Protocol Module. </p> <p><b>API restrictions </b> </p> <p>The SUPL Push API can be used by up to two

threads, each of which must use a different 'channel' as specified by <xref href="GUID-EDDB3400-9EBC-3518-8047-D49C4A261C08.dita"><apiname>_TLbsSuplPushChannel</apiname></xref>.

An API client specifies the channel it wants to use when it calls <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita#GUID-A55B3609-097F-3D14-80FF-76ADA5462621/GUID-75549F72-F22C-3B6B-92D4-20BDE7441AFE"><apiname>CLbsSuplPush::NewL()</apiname></xref>.

Two channels are defined: <codeph>ELbsSuplPushChannelWAP</codeph> and <codeph>ELbsSuplPushChannelSMS</codeph>. </p> <p>A

single thread in an API client can create multiple instances of <codeph>CLbsSuplPush</codeph>,

but each instance must use the same channel. </p> <p>The Symbian WAP Push

Framework instantiates multiple copies of the SUPL WAP Push plug-in to handle

multiple <codeph>SUPL INIT</codeph> messages. All of the instances are started

by the same WAP Push Framework thread. </p> <p>There is only one instance

of the Symbian test SUPL SMS Trigger plug-in which is loaded by the Messaging

Watcher Framework and all messages are processed by the same thread. </p> <p>Licensees

who implement their own method of handing <codeph>SUPL              INIT</codeph> messages

without using the Symbian WAP Push Framework or the Watcher Framework must

remember the API limitations: </p> <ul>

<li id="GUID-87B4BB23-DCE8-5E50-A357-DAFA8DA85612"><p>A maximum total of two

threads can use the API concurrently. </p> </li>

<li id="GUID-16660648-A891-518F-8817-E5DFB00CFDC8"><p>Each thread must use

a different 'channel'. </p> </li>

</ul> <p><b>SUPL

Push API receiver classes</b> </p> <p>This section describes the classes of

the SUPL Push API that the SUPL Protocol Module uses to receive <codeph>SUPL

INIT</codeph> messages. </p> <p>Figure 3 shows the SUPL Push API receiver

classes. Symbian licensees do not need to use the receiver classes - they

are used by the Symbian reference SUPL Protocol Module. </p> <fig id="GUID-62800587-837F-5EC0-872C-AA505491E3E0">

<title>                 Figure 3: Class diagram of SUPL Push API receiver

classes               </title>

</fig> <table id="GUID-1D1A1ED6-1BEC-575C-98B4-1B93F6F5D1DD">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Class name</entry>

<entry>Description</entry>

<entry>Header file</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-15AFA2A5-E300-3DE0-909D-837ECA25A1B8.dita"><apiname> MLbsSuplPushRecObserver</apiname></xref>  </p> </entry>

<entry><p>The observer interface that the SUPL Protocol Module implements

to receive <codeph>SUPL INIT</codeph> messages sent via <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita"><apiname>CLbsSuplPush</apiname></xref>. </p> </entry>

<entry><p> <filepath>lbsuplpushreceiver.h</filepath>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-FD4CC018-C09B-3B0E-B0BC-A887874A610A.dita"><apiname> CLbsSuplPushRec</apiname></xref>  </p> </entry>

<entry><p>The interface defines a method <codeph>SuplInitComplete()</codeph> to

allow the SUPL protocol module to notify LBS that a <codeph>SUPL INIT</codeph> message

was successfully processed. </p> </entry>

<entry><p> <filepath>lbssuplpushreceiver.h</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The SUPL Protocol Module implements <xref href="GUID-15AFA2A5-E300-3DE0-909D-837ECA25A1B8.dita"><apiname>MLbsSuplPushRecObserver</apiname></xref> to

receive notification of SUPL INIT messages sent by using <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita#GUID-A55B3609-097F-3D14-80FF-76ADA5462621/GUID-5AD5A31B-0DE0-36DF-A19F-E0E57EBCCEA9"><apiname>CLbsSuplPush::SuplInit()</apiname></xref>.

It calls <xref href="GUID-FD4CC018-C09B-3B0E-B0BC-A887874A610A.dita#GUID-FD4CC018-C09B-3B0E-B0BC-A887874A610A/GUID-77430315-2C56-33F0-A553-1E4409A13921"><apiname>CLbsSuplPushRec::NewL()</apiname></xref> to register itself for

notifications. </p> <p>The SUPL Protocol Module calls <xref href="GUID-FD4CC018-C09B-3B0E-B0BC-A887874A610A.dita#GUID-FD4CC018-C09B-3B0E-B0BC-A887874A610A/GUID-9F42BE74-9C52-3BD8-9CD0-0F96214010BD"><apiname>CLbsSuplPushRec::SuplInitComplete()</apiname></xref> to

send notification that a message was received successfully. The method <xref href="GUID-7A1E29E6-CF2C-3B19-BADE-2DDD67F6DC36.dita#GUID-7A1E29E6-CF2C-3B19-BADE-2DDD67F6DC36/GUID-4FC083C9-640B-3CC1-8D8B-3A9AE8E57D17"><apiname>MLbsSuplPushObserver::OnSuplInitComplete()</apiname></xref> is

called to notify the sender that the message was received. </p> </section>

<section id="GUID-84F15E4C-4ABA-48F7-963D-BABB6188906B"><title>Libraries </title> <p>The SUPL Push API is packaged in <filepath>lbssuplpush.dll</filepath>.

Clients link to <filepath>lbssuplpush.lib</filepath>. </p> </section>

<section id="GUID-736CACE9-91BD-4818-8CE2-B60397587CE9"><title>Capabilities</title> <p>API clients require <codeph>NetworkServices</codeph> and <codeph>ReadDeviceData</codeph> capabilities. </p> </section>

<section id="GUID-C5F3D283-D329-4FEC-A19D-19479A35A562"><title>Sequence diagram</title> <p>Figure 4 is a simple sequence

diagram showing the WAP Push plug-in receiving a <codeph>SUPL INIT</codeph> message

and sending it to the SUPL Protocol Module. </p> <p>An SMS Trigger plug-in

would use the channel <codeph>ELbsSuplPushChannelSMS</codeph> with <xref href="GUID-A55B3609-097F-3D14-80FF-76ADA5462621.dita#GUID-A55B3609-097F-3D14-80FF-76ADA5462621/GUID-75549F72-F22C-3B6B-92D4-20BDE7441AFE"><apiname>CLbsSuplPush::NewL()</apiname></xref>. </p> <p>The

error parameter <codeph>aError</codeph> returned in <xref href="GUID-7A1E29E6-CF2C-3B19-BADE-2DDD67F6DC36.dita#GUID-7A1E29E6-CF2C-3B19-BADE-2DDD67F6DC36/GUID-4FC083C9-640B-3CC1-8D8B-3A9AE8E57D17"><apiname>MLbsSuplPushObserver::OnSuplInitComplete()</apiname></xref> is <codeph>KErrNone</codeph> if

the SUPL INIT was successfully processed by the SUPL Protocol Module, but

may be another error code as decribed in the API reference documentation. </p> <p>Note

that the SUPL Protocol Module calls <xref href="GUID-B26D8EEC-9DD0-373C-8B29-38C6AC06390C.dita#GUID-B26D8EEC-9DD0-373C-8B29-38C6AC06390C/GUID-049D2C6E-7892-3223-9AC3-B130E0AE7FCC"><apiname>CSuplPushRec::SuplInitComplete()</apiname></xref> when

the <codeph>SUPL           INIT</codeph> message is received, but this does

not guarantee that the network initiated location request will complete successfully. </p> <fig id="GUID-AF4F52FA-F4CC-58E0-BD6F-5C74BC6B6ECD">

<title>              Figure 4: SUPL Push API sequence diagram            </title>

</fig> </section>

<section id="GUID-202D83AC-6C99-5481-8074-ACFEBD426AE3"><title>References</title> <p>[1] <xref href="http://www.openmobilealliance.org" scope="external">Open Mobile Alliance</xref> Secure

User Plane Location (SUPL) Architecture OMA-AD-SUPL-V1_0-20070615-A </p> </section>

</conbody><related-links>

<link href="GUID-EE07DF44-6B3B-5D9A-A794-C49863597721.dita"><linktext>SUPL    

            Push API Tutorial</linktext></link>

<link href="GUID-CC3454B1-21DA-542E-8949-52C30755AC77.dita"><linktext>SUPL Protocol

                Module Overview</linktext></link>

</related-links></concept>