7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-68F27C54-A339-507B-9DD3-B3701132FE0A" xml:lang="en"><title>WAP |
12 <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 |
13 Push Framework Overview</title><shortdesc>WAP Push Framework is a plug-in framework that supports receiving, |
13 receiving, processing and storing of WAP (Wireless Application Protocol) |
14 processing and storing of WAP (Wireless Application Protocol) push messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 push messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
15 <section><title>Required background</title> <p>Before using this component, |
15 <section id="GUID-7E222D54-98DE-460F-98B3-B5CA6709163A"><title>Required background</title> <p>Before using this component, |
16 you must understand <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom |
16 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> |
17 Framework</xref> and <xref href="http://www.openmobilealliance.org/" scope="external">Open |
17 <section id="GUID-52B5BBB3-74D0-47EA-8FB7-77AA480C73A6"><title>Key concepts and terms</title> <dl> |
18 Mobile Alliance (OMA)</xref> standards. </p> </section> |
|
19 <section><title>Key concepts and terms</title> <dl> |
|
20 <dlentry> |
18 <dlentry> |
21 <dt>Push message</dt> |
19 <dt>Push message</dt> |
22 <dd><p>WAP push messages are specially formatted SMS messages that display |
20 <dd><p>WAP push messages are specially formatted SMS messages that |
23 an alert message to the user, and give the user the option of connecting directly |
21 display an alert message to the user, and give the user the option |
24 to a particular URL through the mobile phone’s WAP Browser; for example, notification |
22 of connecting directly to a particular URL through the mobile phone’s |
25 about a new email. </p> <p>A push message has a header section and a body |
23 WAP Browser; for example, notification about a new email. </p> <p>A push message has a header section and a body section. Header section |
26 section. Header section has <codeph>X-Wap-Application-Id</codeph> and <codeph>Content-Type</codeph> fields. |
24 has <codeph>X-Wap-Application-Id</codeph> and <codeph>Content-Type</codeph> fields. The message body can be any MIME content-type and optionally |
27 The message body can be any MIME content-type and optionally encoded. When |
25 encoded. When a push message is received, the framework parses the |
28 a push message is received, the framework parses the message header and loads |
26 message header and loads an appropriate plug-in to process and store |
29 an appropriate plug-in to process and store the message in a Message Store. </p> </dd> |
27 the message in a Message Store. </p> </dd> |
30 </dlentry> |
28 </dlentry> |
31 <dlentry> |
29 <dlentry> |
32 <dt>Push plug-in</dt> |
30 <dt>Push plug-in</dt> |
33 <dd><p>The handler (plug-in) supported by the framework are known as Push |
31 <dd><p>The handler (plug-in) supported by the framework are known |
34 plug-in, such as Application Handler or Content Handler. </p> </dd> |
32 as Push plug-in, such as Application Handler or Content Handler. </p> </dd> |
35 </dlentry> |
33 </dlentry> |
36 </dl> </section> |
34 </dl> </section> |
37 <section><title>Architecture</title> <p>WAP Push Framework provides support |
35 <section id="GUID-9EEB2332-6DD1-403A-AF97-4C66AD9B6CE6"><title>Architecture</title> <p>WAP Push Framework provides |
38 for connectionless (CL) OTA-WSP push. </p> <p>The main components of the framework |
36 support for connectionless (CL) OTA-WSP push. </p> <p>The main components |
39 are Push Watcher, Application Handler and Content Handler. A Push Watcher |
37 of the framework are Push Watcher, Application Handler and Content |
40 is a plug-in that plug-in to the <xref href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita">Messaging |
38 Handler. A Push Watcher is a plug-in that plug-in to the <xref href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita">Messaging Watcher |
41 Watcher Framework</xref> and is responsible for listening on the WAP Stack |
39 Framework</xref> and is responsible for listening on the WAP Stack |
42 for incoming push messages. Push Watcher after receiving the message, loads |
40 for incoming push messages. Push Watcher after receiving the message, |
43 an appropriate Application Handler through Application Dispatcher. An Application |
41 loads an appropriate Application Handler through Application Dispatcher. |
44 Handler is responsible for loading the appropriate Content Handler using the <codeph>X-Wap-Application-Id</codeph> value |
42 An Application Handler is responsible for loading the appropriate |
|
43 Content Handler using the <codeph>X-Wap-Application-Id</codeph> value |
45 contained in the received push message. The content handler is responsible |
44 contained in the received push message. The content handler is responsible |
46 to handle the push message and take any action on the message that may be |
45 to handle the push message and take any action on the message that |
47 necessary. However, if a plug-in for a given content-type is not available, |
46 may be necessary. However, if a plug-in for a given content-type is |
48 the WAP Push Framework uses the unknown application handler plug-in (default) |
47 not available, the WAP Push Framework uses the unknown application |
49 and discards the push message. </p> <p>The following figure shows the architecture |
48 handler plug-in (default) and discards the push message. </p> <p>The |
50 of WAP Push Framework. </p> <fig id="GUID-359E967A-EA0E-5AE2-A03C-220EB0C74B38"> |
49 following figure shows the architecture of WAP Push Framework. </p> <fig id="GUID-359E967A-EA0E-5AE2-A03C-220EB0C74B38"> |
51 <title> WAP Push Framework Architecture </title> |
50 <title> WAP Push Framework Architecture </title> |
52 <image href="GUID-258FA5F7-5069-5DFE-8F6E-57063064CE65_d0e491086_href.jpg" placement="inline"/> |
51 <image href="GUID-258FA5F7-5069-5DFE-8F6E-57063064CE65_d0e496901_href.jpg" placement="inline"/> |
53 </fig> <dl> |
52 </fig> <dl> |
54 <dlentry> |
53 <dlentry> |
55 <dt>Push Watcher</dt> |
54 <dt>Push Watcher</dt> |
56 <dd><p>There are two Push Watchers in the framework for CL OTA-WSP—one is |
55 <dd><p>There are two Push Watchers in the framework for CL OTA-WSP—one |
57 for secure push and the other is for non-secure push. The insecure CL watcher |
56 is for secure push and the other is for non-secure push. The insecure |
58 is always active and waits asynchronously to receive message from WAP Stack |
57 CL watcher is always active and waits asynchronously to receive message |
59 at port 2948. On receiving a push message, the watcher wraps the message up |
58 from WAP Stack at port 2948. On receiving a push message, the watcher |
60 in a <xref href="GUID-C52CFBC5-40D0-3B55-B17F-F3709B8D960B.dita"><apiname>CPushMessage</apiname></xref>, parses the message and calls the Application |
59 wraps the message up in a <xref href="GUID-C52CFBC5-40D0-3B55-B17F-F3709B8D960B.dita"><apiname>CPushMessage</apiname></xref>, parses |
61 Dispatcher, passing in the <codeph>X-Wap-Application-Id</codeph> value obtained |
60 the message and calls the Application Dispatcher, passing in the <codeph>X-Wap-Application-Id</codeph> value obtained from the push message. </p> </dd> |
62 from the push message. </p> </dd> |
|
63 </dlentry> |
61 </dlentry> |
64 <dlentry> |
62 <dlentry> |
65 <dt>Dispatchers and Handlers</dt> |
63 <dt>Dispatchers and Handlers</dt> |
66 <dd><p>The framework contains an Application Dispatcher and a Content Dispatcher |
64 <dd><p>The framework contains an Application Dispatcher and a Content |
67 that are used to find the appropriate Application Handler and Content Handler |
65 Dispatcher that are used to find the appropriate Application Handler |
68 respectively. </p> <p>Application Dispatcher uses ECom to load an Application |
66 and Content Handler respectively. </p> <p>Application Dispatcher uses |
69 Handler using the application-ID passed to it by the Push Watcher. Two different |
67 ECom to load an Application Handler using the application-ID passed |
70 Application Handlers are present in the framework—Unknown Application Handler |
68 to it by the Push Watcher. Two different Application Handlers are |
71 for applications of unknown type and User Agent (UA) Application Handler that |
69 present in the framework—Unknown Application Handler for applications |
72 receives messages of type ‘<b>x-wap-application:*</b> ’ or ‘<b>x-wap-application:wml.ua</b> ’. |
70 of unknown type and User Agent (UA) Application Handler that receives |
73 The UA Application Handler looks at the content-type of the message and passes |
71 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 |
74 it to the Content Dispatcher. The content dispatcher then loads an appropriate |
72 and passes it to the Content Dispatcher. The content dispatcher then |
75 Content Handler. The Unknown Application Handler deletes the push message. </p> <p>The |
73 loads an appropriate Content Handler. The Unknown Application Handler |
76 Content Dispatcher uses ECom to load a particular Content Handler (plug-in) |
74 deletes the push message. </p> <p>The Content Dispatcher uses ECom |
77 based on the content-type passed in by the Application Handler. The following |
75 to load a particular Content Handler (plug-in) based on the content-type |
78 are the Content Handlers provided within the framework. </p> <ul> |
76 passed in by the Application Handler. The following are the Content |
79 <li id="GUID-9A90410A-354F-5492-AF7C-562729E12960"><p> <b>SI Content Handler:</b> These |
77 Handlers provided within the framework. </p> <ul> |
80 plug-ins process Service Indication (SI) messages. An SI message is a UA message |
78 <li id="GUID-9A90410A-354F-5492-AF7C-562729E12960"><p> <b>SI Content |
81 with content-type <filepath>text/vnd.wap.si</filepath> or <filepath>application/vnd.wap.sic</filepath>. |
79 Handler:</b> These plug-ins process Service Indication (SI) messages. |
82 The basic form of an SI message is a short message with a URI indicating a |
80 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 |
83 service; for example, notification about new emails. </p> </li> |
81 of an SI message is a short message with a URI indicating a service; |
84 <li id="GUID-63867E1C-1B2A-50E8-9FBE-3C127DA96EEB"><p> <b>SL Content Handler:</b> These |
82 for example, notification about new emails. </p> </li> |
85 plug-ins process Service Load (SL) messages. An SL message is an UA message |
83 <li id="GUID-63867E1C-1B2A-50E8-9FBE-3C127DA96EEB"><p> <b>SL Content |
86 with content-type <filepath>text/vnd.wap.sl</filepath> or <filepath>application/vnd.wap.slc</filepath>. |
84 Handler:</b> These plug-ins process Service Load (SL) messages. An |
87 The SL message contains a URI indicating a service which gets loaded without |
85 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 |
88 user input. </p> </li> |
86 contains a URI indicating a service which gets loaded without user |
|
87 input. </p> </li> |
89 <li id="GUID-56EACABF-8948-5490-A225-174920E5B4C1"><p> <b>Multipart-mixed |
88 <li id="GUID-56EACABF-8948-5490-A225-174920E5B4C1"><p> <b>Multipart-mixed |
90 Content Handler:</b> These plug-ins process multipart-mixed messages. These |
89 Content Handler:</b> These plug-ins process multipart-mixed messages. |
91 are messages with content-type <filepath>application/vnd.wap.multipart.mixed</filepath> or <filepath>multipart/mixed</filepath>. |
90 These are messages with content-type <filepath>application/vnd.wap.multipart.mixed</filepath> or <filepath>multipart/mixed</filepath>. They create new sub-messages |
92 They create new sub-messages from each message part, and load appropriate |
91 from each message part, and load appropriate content handler plug-ins |
93 content handler plug-ins to process each sub-message. </p> </li> |
92 to process each sub-message. </p> </li> |
94 <li id="GUID-8FFDB2E9-399D-5EA7-82E3-A50952697B29"><p> <b>Multipart-related, |
93 <li id="GUID-8FFDB2E9-399D-5EA7-82E3-A50952697B29"><p> <b>Multipart-related, |
95 Multipart-alternative Content Handlers:</b> These plug-ins process messages |
94 Multipart-alternative Content Handlers:</b> These plug-ins process |
96 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 |
95 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 |
97 entire message in the Message Store, where each part is saved as a child entry |
96 the entire message in the Message Store, where each part is saved |
98 to the main part. </p> </li> |
97 as a child entry to the main part. </p> </li> |
99 <li id="GUID-9AA16C02-F759-541D-B850-719716065F52"><p> <b>Unknown Content |
98 <li id="GUID-9AA16C02-F759-541D-B850-719716065F52"><p> <b>Unknown |
100 Handler:</b> These plug-ins process content-types for which there are no handler |
99 Content Handler:</b> These plug-ins process content-types for which |
101 plug-ins. They store the received push messages in Inbox of the Message Store. </p> </li> |
100 there are no handler plug-ins. They store the received push messages |
|
101 in Inbox of the Message Store. </p> </li> |
102 </ul> </dd> |
102 </ul> </dd> |
103 </dlentry> |
103 </dlentry> |
104 </dl> </section> |
104 </dl> </section> |
105 <section><title>APIs</title> <table id="GUID-F6247FC0-87AC-5F7F-8965-8F10E9B8ACAC"> |
105 <section id="GUID-48F54813-3327-45FB-B923-BA6E9C245993"><title>APIs</title> <table id="GUID-F6247FC0-87AC-5F7F-8965-8F10E9B8ACAC"> |
106 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
106 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
107 <thead> |
107 <thead> |
108 <row> |
108 <row> |
109 <entry>API</entry> |
109 <entry>API</entry> |
110 <entry>Description</entry> |
110 <entry>Description</entry> |
120 <entry><p>Abstract base class for WAP Push Content Handler plug-ins. </p> </entry> |
120 <entry><p>Abstract base class for WAP Push Content Handler plug-ins. </p> </entry> |
121 </row> |
121 </row> |
122 </tbody> |
122 </tbody> |
123 </tgroup> |
123 </tgroup> |
124 </table> </section> |
124 </table> </section> |
125 <section><title>Typical uses</title> <p>WAP Push Framework is extensible, |
125 <section id="GUID-D677C8B2-BFEB-496C-B481-10497537B31C"><title>Typical uses</title> <p>WAP Push Framework is extensible, |
126 that is, new plug-ins can be installed to the framework and installed plug-ins |
126 that is, new plug-ins can be installed to the framework and installed |
127 can be removed from the framework without re-building the framework. It uses |
127 plug-ins can be removed from the framework without re-building the |
128 dynamically loaded plug-ins at run-time to support different content-types; |
128 framework. It uses dynamically loaded plug-ins at run-time to support |
129 for example, content of push message for Service Indicator (SI) application. |
129 different content-types; for example, content of push message for |
130 ECom Framework is used to provide support for run-time loading. </p> <ul> |
130 Service Indicator (SI) application. ECom Framework is used to provide |
131 <li id="GUID-7B03A6BF-D191-568F-8442-5842AC48C2E0"><p>Creating content handler |
131 support for run-time loading. </p> <ul> |
132 plug-ins. </p> <p> <b>Note:</b> Push plug-ins must inherit from the base push |
132 <li id="GUID-7B03A6BF-D191-568F-8442-5842AC48C2E0"><p>Creating content |
133 plug-in class and override a set of pure virtual functions. </p> </li> |
133 handler plug-ins. </p> <p> <b>Note:</b> Push plug-ins must inherit |
134 <li id="GUID-CE7A22B1-D1B2-5CDD-ACF7-9D9FB0A0DC63"><p>Removing any installed |
134 from the base push plug-in class and override a set of pure virtual |
135 plug-ins. </p> </li> |
135 functions. </p> </li> |
|
136 <li id="GUID-CE7A22B1-D1B2-5CDD-ACF7-9D9FB0A0DC63"><p>Removing any |
|
137 installed plug-ins. </p> </li> |
136 </ul> </section> |
138 </ul> </section> |
137 </conbody><related-links> |
139 </conbody><related-links> |
138 <link href="http://www.openmobilealliance.org/.dita"><linktext>Open Mobile |
140 <link href="http://www.openmobilealliance.org/" scope="external"> |
139 Alliance (OMA)</linktext></link> |
141 <linktext>Open Mobile Alliance (OMA)</linktext></link> |
140 <link href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita"><linktext>Watcher Framework</linktext> |
142 <link href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita"><linktext>Watcher |
141 </link> |
143 Framework</linktext></link> |
142 <link href="GUID-EE07DF44-6B3B-5D9A-A794-C49863597721.dita"><linktext>SUPL |
144 <link href="GUID-EE07DF44-6B3B-5D9A-A794-C49863597721.dita"><linktext>SUPL |
143 Push API Tutorial</linktext></link> |
145 Push API Tutorial</linktext></link> |
144 </related-links></concept> |
146 </related-links></concept> |