--- a/Symbian3/PDK/Source/GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,28 +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 xml:lang="en" id="GUID-E7DD9CFD-F477-5D25-BC10-BEBFB1022F7E"><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: The SUPL Push API is deprecated. </p> <section><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><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><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_d0e443654_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><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_d0e443755_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_d0e443974_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><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><title>Capabilities</title> <p>API clients require <codeph>NetworkServices</codeph> and <codeph>ReadDeviceData</codeph> capabilities. </p> </section> <section><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_d0e444161_href.png" placement="inline"/></fig> </section> <section id="GUID-202D83AC-6C99-5481-8074-ACFEBD426AE3"><title>References</title> <p>[1] <xref scope="external" href="http://www.openmobilealliance.org">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
+<?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>
\ No newline at end of file