<?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 id="GUID-7E222D54-98DE-460F-98B3-B5CA6709163A"><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 id="GUID-52B5BBB3-74D0-47EA-8FB7-77AA480C73A6"><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 id="GUID-9EEB2332-6DD1-403A-AF97-4C66AD9B6CE6"><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_d0e496901_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 id="GUID-48F54813-3327-45FB-B923-BA6E9C245993"><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 id="GUID-D677C8B2-BFEB-496C-B481-10497537B31C"><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/" scope="external">
<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>