<?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-68F27C54-A339-507B-9DD3-B3701132FE0A" xml:lang="en"><title>WAP
Push Framework Overview</title><shortdesc>WAP Push Framework is a plug-in framework that supports receiving,
processing and storing of WAP (Wireless Application Protocol) push messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Required background</title> <p>Before using this component,
you must understand <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom
Framework</xref> and <xref href="http://www.openmobilealliance.org/" scope="external">Open
Mobile Alliance (OMA)</xref> standards. </p> </section>
<section><title>Key concepts and terms</title> <dl>
<dlentry>
<dt>Push message</dt>
<dd><p>WAP push messages are specially formatted SMS messages that display
an alert message to the user, and give the user the option of connecting directly
to a particular URL through the mobile phone’s WAP Browser; for example, notification
about a new email. </p> <p>A push message has a header section and a body
section. Header section has <codeph>X-Wap-Application-Id</codeph> and <codeph>Content-Type</codeph> fields.
The message body can be any MIME content-type and optionally encoded. When
a push message is received, the framework parses the message header and loads
an appropriate plug-in to process and store the message in a Message Store. </p> </dd>
</dlentry>
<dlentry>
<dt>Push plug-in</dt>
<dd><p>The handler (plug-in) supported by the framework are known as Push
plug-in, such as Application Handler or Content Handler. </p> </dd>
</dlentry>
</dl> </section>
<section><title>Architecture</title> <p>WAP Push Framework provides support
for connectionless (CL) OTA-WSP push. </p> <p>The main components of the framework
are Push Watcher, Application Handler and Content Handler. A Push Watcher
is a plug-in that plug-in to the <xref href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita">Messaging
Watcher Framework</xref> and is responsible for listening on the WAP Stack
for incoming push messages. Push Watcher after receiving the message, loads
an appropriate Application Handler through Application Dispatcher. An Application
Handler is responsible for loading the appropriate Content Handler using the <codeph>X-Wap-Application-Id</codeph> value
contained in the received push message. The content handler is responsible
to handle the push message and take any action on the message that may be
necessary. However, if a plug-in for a given content-type is not available,
the WAP Push Framework uses the unknown application handler plug-in (default)
and discards the push message. </p> <p>The following figure shows the architecture
of WAP Push Framework. </p> <fig id="GUID-359E967A-EA0E-5AE2-A03C-220EB0C74B38">
<title>              WAP Push Framework Architecture            </title>
<image href="GUID-258FA5F7-5069-5DFE-8F6E-57063064CE65_d0e500921_href.jpg" placement="inline"/>
</fig> <dl>
<dlentry>
<dt>Push Watcher</dt>
<dd><p>There are two Push Watchers in the framework for CL OTA-WSP—one is
for secure push and the other is for non-secure push. The insecure CL watcher
is always active and waits asynchronously to receive message from WAP Stack
at port 2948. On receiving a push message, the watcher wraps the message up
in a <xref href="GUID-C52CFBC5-40D0-3B55-B17F-F3709B8D960B.dita"><apiname>CPushMessage</apiname></xref>, parses the message and calls the Application
Dispatcher, passing in the <codeph>X-Wap-Application-Id</codeph> value obtained
from the push message. </p> </dd>
</dlentry>
<dlentry>
<dt>Dispatchers and Handlers</dt>
<dd><p>The framework contains an Application Dispatcher and a Content Dispatcher
that are used to find the appropriate Application Handler and Content Handler
respectively. </p> <p>Application Dispatcher uses ECom to load an Application
Handler using the application-ID passed to it by the Push Watcher. Two different
Application Handlers are present in the framework—Unknown Application Handler
for applications of unknown type and User Agent (UA) Application Handler that
receives messages of type ‘<b>x-wap-application:*</b> ’ or ‘<b>x-wap-application:wml.ua</b> ’.
The UA Application Handler looks at the content-type of the message and passes
it to the Content Dispatcher. The content dispatcher then loads an appropriate
Content Handler. The Unknown Application Handler deletes the push message. </p> <p>The
Content Dispatcher uses ECom to load a particular Content Handler (plug-in)
based on the content-type passed in by the Application Handler. The following
are the Content Handlers provided within the framework. </p> <ul>
<li id="GUID-9A90410A-354F-5492-AF7C-562729E12960"><p> <b>SI Content Handler:</b> These
plug-ins process Service Indication (SI) messages. An SI message is a UA message
with content-type <filepath>text/vnd.wap.si</filepath> or <filepath>application/vnd.wap.sic</filepath>.
The basic form of an SI message is a short message with a URI indicating a
service; for example, notification about new emails. </p> </li>
<li id="GUID-63867E1C-1B2A-50E8-9FBE-3C127DA96EEB"><p> <b>SL Content Handler:</b> These
plug-ins process Service Load (SL) messages. An SL message is an UA message
with content-type <filepath>text/vnd.wap.sl</filepath> or <filepath>application/vnd.wap.slc</filepath>.
The SL message contains a URI indicating a service which gets loaded without
user input. </p> </li>
<li id="GUID-56EACABF-8948-5490-A225-174920E5B4C1"><p> <b>Multipart-mixed
Content Handler:</b> These plug-ins process multipart-mixed messages. These
are messages with content-type <filepath>application/vnd.wap.multipart.mixed</filepath> or <filepath>multipart/mixed</filepath>.
They create new sub-messages from each message part, and load appropriate
content handler plug-ins to process each sub-message. </p> </li>
<li id="GUID-8FFDB2E9-399D-5EA7-82E3-A50952697B29"><p> <b>Multipart-related,
Multipart-alternative Content Handlers:</b> These plug-ins process messages
for the <filepath>application/vnd.wap.multipart.alternative</filepath>, <filepath>multipart/alternative</filepath>, <filepath>application/vnd.wap</filepath> and <filepath>multipart.related</filepath> content-types. They save the
entire message in the Message Store, where each part is saved as a child entry
to the main part. </p> </li>
<li id="GUID-9AA16C02-F759-541D-B850-719716065F52"><p> <b>Unknown Content
Handler:</b> These plug-ins process content-types for which there are no handler
plug-ins. They store the received push messages in Inbox of the Message Store. </p> </li>
</ul> </dd>
</dlentry>
</dl> </section>
<section><title>APIs</title> <table id="GUID-F6247FC0-87AC-5F7F-8965-8F10E9B8ACAC">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>API</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-23D181F0-AF1E-3221-BF9A-AC3534E961E9.dita"><apiname>CPushHandlerBase</apiname></xref>  </p> </entry>
<entry><p>Abstract base class for WAP Push Application plug-ins. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-56BCBAED-03E5-35D6-A828-9B48ACEBF085.dita"><apiname>CContentHandlerBase</apiname></xref>  </p> </entry>
<entry><p>Abstract base class for WAP Push Content Handler plug-ins. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section><title>Typical uses</title> <p>WAP Push Framework is extensible,
that is, new plug-ins can be installed to the framework and installed plug-ins
can be removed from the framework without re-building the framework. It uses
dynamically loaded plug-ins at run-time to support different content-types;
for example, content of push message for Service Indicator (SI) application.
ECom Framework is used to provide support for run-time loading. </p> <ul>
<li id="GUID-7B03A6BF-D191-568F-8442-5842AC48C2E0"><p>Creating content handler
plug-ins. </p> <p> <b>Note:</b> Push plug-ins must inherit from the base push
plug-in class and override a set of pure virtual functions. </p> </li>
<li id="GUID-CE7A22B1-D1B2-5CDD-ACF7-9D9FB0A0DC63"><p>Removing any installed
plug-ins. </p> </li>
</ul> </section>
</conbody><related-links>
<link href="http://www.openmobilealliance.org/.dita"><linktext>Open Mobile    
            Alliance (OMA)</linktext></link>
<link href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita"><linktext>Watcher Framework</linktext>
</link>
<link href="GUID-EE07DF44-6B3B-5D9A-A794-C49863597721.dita"><linktext>SUPL
                Push API Tutorial</linktext></link>
</related-links></concept>