<?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_d0e479868_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>