Week 12 contribution of PDK documentation_content. See release notes for details. Fixes Bug 2054, Bug 1583, Bug 381, Bug 390, Bug 463, Bug 1897, Bug 344, Bug 1319, Bug 394, Bug 1520, Bug 1522, Bug 1892"
<?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>
<image href="GUID-398483AD-C341-5777-AD23-381A067F9180_d0e465628_href.png" placement="inline"/>
</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><LBS_SOURCE_ROOT>/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><LBS_SOURCE_ROOT>/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>
<image href="GUID-0A24FF35-5A61-5305-812B-632F20F0395D_d0e465732_href.png" placement="inline"/>
</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&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&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&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>
<image href="GUID-120CA508-9984-54D0-B366-6D10D646FD49_d0e465962_href.png" placement="inline"/>
</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>
<image href="GUID-84623607-ACCA-5E57-9001-DA56E16C1652_d0e466158_href.png" placement="inline"/>
</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>