--- a/Symbian3/PDK/Source/GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita Fri Jun 11 12:39:03 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita Fri Jun 11 15:24:34 2010 +0100
@@ -1,236 +1,236 @@
-<?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>
+<?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_d0e454195_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_d0e454299_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_d0e454529_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_d0e454725_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>
\ No newline at end of file