|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268" xml:lang="en"><title>Using |
|
13 the Class 0 Plug-in for Class 0 SMS</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This section describes an ECom plug-in called <b>Class 0 </b> plug-in for |
|
15 the messaging subsystem which handles <b>Class 0</b> SMS. </p> |
|
16 <section><title>Overview</title> <p>Class 0 SMS is a type of SMS message that |
|
17 is displayed on the mobile screen without being saved in the message store |
|
18 or on the SIM card; unless explicitly saved by the mobile user. The Class |
|
19 0 plug-in handles and displays Class 0 SMS. </p> <p>Using this plug-in, the |
|
20 Symbian Messaging subsystem does not store Class 0 SMS in the message store |
|
21 (SMS service Inbox), but immediately displays them on the mobile screen; even |
|
22 if there is no memory available on the SIM or device. For more detailed information |
|
23 on how Class 0 messages are handled by the Symbian Messaging subsystem, see |
|
24 the <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-42CA3291-7C12-52F3-9F1E-7A16E740FB89">Architecture</xref> section. </p> <p><b>SMS stack configuration</b> </p> <p>The SMS stack must be configured to |
|
25 handle Class 0 SMS. This is done in accordance with the SMS stack licence. |
|
26 If the SMS stack is not configured to handle Class 0 messages they will be |
|
27 treated as non Class 0 SMS. They will be stored in the message store and are |
|
28 notified to the UI framework. For more information on configuration of the |
|
29 SMS stack to handle Class 0 messages, see <xref href="GUID-266B3FD6-A414-599D-BF31-FF67ADDD4E70.dita">Configuring |
|
30 SMS Stack To Handle Class 0 Messages</xref>. </p><note> WAP messages that |
|
31 use Class 0 SMS are treated as non Class 0 SMS.</note><p>Symbian provides |
|
32 a default plug-in as part of the Symbian Messaging subsystem. However, licensees |
|
33 can override it by writing a new ECom plug-in using the <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> class. |
|
34 For more information on <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref>, see <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-B6EECACA-77D1-57AF-A7F9-4ECE7E911C38">Writing a new plug-in using CSmsClass0Base class</xref>.</p> </section> |
|
35 <section id="GUID-42CA3291-7C12-52F3-9F1E-7A16E740FB89"><title>Architecture</title> <p>The |
|
36 Class 0 plug-in is loaded by the Narrow Band Socket (NBS) watcher when it |
|
37 starts. The NBS watcher looks for the Class 0 plug-in ROM only. When the NBS |
|
38 watcher receives an SMS message from the SMS stack, it checks for the type |
|
39 of SMS message. If it is a Class 0 SMS message, the NBS watcher passes the |
|
40 message to the Class 0 plug-in. The Class 0 plug-in immediately notifies a |
|
41 UI notifier plug-in which displays the content of the Class 0 SMS message |
|
42 on the UI without storing it in the message store (SMS service Inbox). </p> <fig id="GUID-9768EB50-2605-5181-AB53-7376A4B82272"> |
|
43 <title> Architecture of the Class 0 plug-in </title> |
|
44 <image href="GUID-EC6C21FB-16E1-57FA-B995-8B0F34B6588A_d0e477912_href.png" placement="inline"/> |
|
45 </fig> <dl> |
|
46 <dlentry> |
|
47 <dt>SMS stack</dt> |
|
48 <dd><p>SMS Stack sends and receives SMS on GSM networks. </p> </dd> |
|
49 </dlentry> |
|
50 <dlentry> |
|
51 <dt>NBS watcher</dt> |
|
52 <dd><p>NBS watcher handles reception of SMS and listens to the following special |
|
53 SMS received from the SMS stack: </p> <ul> |
|
54 <li id="GUID-5EC44BF6-BEAB-5716-9ADD-81E9A4DA8420"><p>Replace type messages </p> </li> |
|
55 <li id="GUID-9698F7AD-0E2E-58FE-81FA-DAA1AFDB9A2C"><p>Message indications </p> </li> |
|
56 <li id="GUID-1164E798-FBFA-5C32-B031-FC5158D35083"><p>Delivery reports </p> </li> |
|
57 </ul> </dd> |
|
58 </dlentry> |
|
59 </dl> </section> |
|
60 <section id="GUID-B6EECACA-77D1-57AF-A7F9-4ECE7E911C38"><title>Writing a new |
|
61 plug-in using the CSmsClass0Base class</title> <p>The Symbian Messaging subsystem |
|
62 includes a default implementation of the <codeph>CSmsClass0Base</codeph> plug-in |
|
63 which can be found in the <filepath>class0sms.dll</filepath> file. </p> <p>However, |
|
64 licensees can override it by writing a new ECom plug-in using the <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> exported |
|
65 class. For instructions on writing a new ECom plug-in, see the <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">ECom</xref> guide. </p> <fig id="GUID-89F37A8E-78B2-5BEE-A066-90A186687FCA"> |
|
66 <title> Class diagram </title> |
|
67 <image href="GUID-B479BE8B-5CAD-57C2-9E21-DEB9E64E25EE_d0e477987_href.png" placement="inline"/> |
|
68 </fig> <p> <codeph>void CClass0Sms::DisplayMessageHandler(TDesC8& aSmsMessage, |
|
69 TBool aIsCompleteMsg)</codeph> </p> <table id="GUID-F3506200-AB0D-56EB-9C18-70E83B818ABA"> |
|
70 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
71 <tbody> |
|
72 <row> |
|
73 <entry><p> <xref href="GUID-E6FE50CD-CA6D-3377-8936-F2053330FF80.dita"><apiname>CClass0Sms</apiname></xref> </p> </entry> |
|
74 <entry><p>Derived from the <xref href="GUID-93BFA177-A165-3955-A5BC-D7D35C5EFE49.dita"><apiname>CSmsClass0Base</apiname></xref> class </p> </entry> |
|
75 </row> |
|
76 <row> |
|
77 <entry><p> <xref href="GUID-50DE662C-DB6E-3149-B0F3-6740BF7989E9.dita"><apiname>DisplayMessageHandler</apiname></xref> </p> </entry> |
|
78 <entry><p>This method calls <xref href="GUID-C6382C9D-1AE1-3B11-9B51-9D29D902254B.dita"><apiname>StartNotifier()</apiname></xref> or <xref href="GUID-9475FFE9-37AC-3B6C-9312-577D951DE191.dita"><apiname>UpdateNotifier()</apiname></xref> according |
|
79 to the value set in the aIsCompleteMsg flag. </p> </entry> |
|
80 </row> |
|
81 <row> |
|
82 <entry><p> <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> <codeph>& aSmsMessage</codeph> </p> </entry> |
|
83 <entry><p>Contains the following data: </p> <ul> |
|
84 <li id="GUID-CFE508B0-7546-5F34-9B22-63648DEE1235"><p>Starting PDU (Protocol |
|
85 Data Unit) position of the decoded message </p> </li> |
|
86 <li id="GUID-AE21C54C-FA96-5921-8FD2-64A886C311AA"><p>Ending PDU position |
|
87 of the decoded message </p> </li> |
|
88 <li id="GUID-BC00D3B1-2254-5A5C-8E09-8DBBA87320C8"><p>Boolean value indicating |
|
89 if it is a last incomplete message. </p> </li> |
|
90 <li id="GUID-DE984CF4-308B-56B2-B935-9EF711E10B26"><p>Class 0 SMS data </p> </li> |
|
91 </ul> <p>The data needs be extracted at the client side in same order; that |
|
92 is, <codeph>TInt aStartPos</codeph>, <codeph>TInt endPos</codeph>, <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsLastMessage</codeph>, |
|
93 and <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> <codeph> aSmsData</codeph>. </p> </entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><p> <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsCompleteMsg</codeph> </p> </entry> |
|
97 <entry><p>Indicates whether the message is a complete or partial message. </p> </entry> |
|
98 </row> |
|
99 </tbody> |
|
100 </tgroup> |
|
101 </table> <p>This class calls <codeph>RNotifier::StartNotifier</codeph> or <codeph>RNotifier::UpdateNotifier</codeph> according |
|
102 to the <codeph>aIsCompleteMsg</codeph> flag setting as illustrated in the |
|
103 following code example: </p> <codeblock id="GUID-8695AEDE-4F2D-5379-BA42-23374176F3D3" xml:space="preserve">void CClass0Sms::DisplayMessageHandler(TDesC8& aSmsMessage, TBool aIsCompleteMsg) |
|
104 { |
|
105 TPckgBuf<TInt> response; |
|
106 |
|
107 if(aIsCompleteMsg) |
|
108 { |
|
109 //The UID of KUidClass0SmsNotifier should to be used in UI Notifier. |
|
110 iNotifier.StartNotifier(KUidClass0SmsNotifier, aSmsMessage); |
|
111 } |
|
112 else |
|
113 { |
|
114 //The UID of KUidClass0SmsNotifier should to be used in UI Notifier. |
|
115 iNotifier.UpdateNotifier(KUidClass0SmsNotifier, aSmsMessage, response); |
|
116 } |
|
117 }</codeblock> <p>For more details on writing a UI Notifier, see <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F">Example</xref>. </p> </section> |
|
118 <section><title>Understanding types of Class 0 SMS</title> <p>The SMS stack |
|
119 can send a complete or partial messages to the Messaging client. When it sends |
|
120 a partial message to the Messaging client, such as in an out-of-disk condition, |
|
121 it provides additional information about the partial message. </p> <p>The |
|
122 following are the type of Class 0 SMS message displayed on the UI framework. </p><table id="GUID-31075134-4116-45C7-9905-D06A0F73C759"> |
|
123 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
124 <tbody> |
|
125 <row> |
|
126 <entry><p><b>Type of Class 0 SMS message </b></p></entry> |
|
127 <entry><p><b>Displayed on the UI framework</b></p></entry> |
|
128 </row> |
|
129 <row> |
|
130 <entry><p>Complete </p></entry> |
|
131 <entry><p>If the received message is complete, it contains the Class 0 SMS |
|
132 data and the remaining fields are set to zero (0).</p><codeblock xml:space="preserve">StartPos:0EndPos:0IsCompleteMsg: EFalse</codeblock></entry> |
|
133 </row> |
|
134 <row> |
|
135 <entry><p>Partial </p></entry> |
|
136 <entry><p>If the received message is incomplete, it contains information about |
|
137 the starting and ending PDU positions of the decoded message, and the <codeph>isCompleteMessageFlag</codeph> flag |
|
138 is set to <codeph>EFalse</codeph>. </p><codeblock xml:space="preserve">StartPos: StartingPDUpositionEndPos: EndingPDUpositionisLastMessage: ETrue</codeblock><p>If it is the last part of the partial message, then <codeph>IsCompleteMessageFlag</codeph> will |
|
139 be set to <codeph>EFalse</codeph>. </p></entry> |
|
140 </row> |
|
141 </tbody> |
|
142 </tgroup> |
|
143 </table> </section> |
|
144 <section><title>Extracting the serial buffer</title> <p>The Symbian Messaging |
|
145 subsystem passes the serial buffer, which contains starting and ending PDU, |
|
146 and the Class 0 SMS message in the <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> descriptor to |
|
147 the UI. The <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> descriptor must be read at the UI side |
|
148 in the same order; that is, <codeph>TInt aStartPos</codeph>, <codeph>TInt |
|
149 endPos</codeph>, <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> <codeph> aIsLastMessage</codeph>, |
|
150 and <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> <codeph> aSmsData</codeph>. </p> </section> |
|
151 <section id="GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F-GENID-1-7-1-17-1-1-6-1-6-1-4-1-2-7"><title>Example</title> <p>The |
|
152 following example code shows how to write a UI notifier and extract the Class |
|
153 0 SMS message: </p> <p><b>class0smsUInotifier.h</b> </p> <codeblock id="GUID-88CC9E44-3C8C-522B-83D3-658EEEEE928D" xml:space="preserve">// class0smsUInotifier.h |
|
154 // |
|
155 // Copyright ©) Symbian Software Ltd 2007. All rights reserved. |
|
156 // |
|
157 |
|
158 #ifndef __CLASS0SMSUINOTIFIER_H__ |
|
159 #define __CLASS0SMSUINOTIFIER_H__ |
|
160 |
|
161 #include <eiknotapi.h> |
|
162 #include <ecom.h> |
|
163 |
|
164 class CClass0SmsUINotifier : public MEikSrvNotifierBase2 |
|
165 { |
|
166 public: |
|
167 // Construction |
|
168 static CClass0SmsUINotifier* NewL(); |
|
169 ~CClass0SmsUINotifier(); |
|
170 private: |
|
171 CClass0SmsUINotifier(); |
|
172 void ConstructL(); |
|
173 |
|
174 // from MEikSrvNotifierBase2 |
|
175 virtual void Release(); |
|
176 virtual TNotifierInfo RegisterL(); |
|
177 virtual TNotifierInfo Info() const; |
|
178 virtual TPtrC8 StartL(const TDesC8& aBuffer); |
|
179 virtual void Cancel(); |
|
180 virtual TPtrC8 UpdateL(const TDesC8& aBuffer); |
|
181 void ExtractClass0SMSData(const TDesC8& aBuffer); |
|
182 |
|
183 private: |
|
184 TNotifierInfo iInfo; |
|
185 }; |
|
186 |
|
187 #endif // __CLASS0SMSUINOTIFIER_H__ |
|
188 </codeblock> <p><b>class0smsUInotifier.cpp</b> </p> <codeblock id="GUID-E7C55266-C174-59A2-B926-A7F3E0496B5C" xml:space="preserve">// class0smsUInotifier.cpp |
|
189 // |
|
190 // Copyright ©) Symbian Software Ltd 2007. All rights reserved. |
|
191 // |
|
192 #include <ecom.h> |
|
193 #include <tmsvpackednotifierrequest.h> |
|
194 #include <implementationproxy.h> |
|
195 #include <gsmubuf.h> |
|
196 #include <s32mem.h> |
|
197 #include <e32base.h> |
|
198 #include "class0smsUInotifier.h" |
|
199 |
|
200 |
|
201 // The UID identifying the notifier, |
|
202 // this UID is used in RNotifier::StartNotifier/RNotifier::UpdateNotifier to send the class 0 SMS message from messaging application. |
|
203 |
|
204 const TUid KUidClass0SmsNotifier = {0x2000C382}; |
|
205 const TUid KClass0SmsNotifierOutput = {0x2000C382}; |
|
206 |
|
207 |
|
208 EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() |
|
209 { |
|
210 CArrayPtrFlat<MEikSrvNotifierBase2>* subjects=NULL; |
|
211 TRAPD( err, subjects=new (ELeave)CArrayPtrFlat<MEikSrvNotifierBase2>(1) ); |
|
212 if( err == KErrNone ) |
|
213 { |
|
214 TRAP( err, subjects->AppendL( CClass0SmsUINotifier::NewL() ) ); |
|
215 return(subjects); |
|
216 } |
|
217 else |
|
218 { |
|
219 return NULL; |
|
220 } |
|
221 } |
|
222 |
|
223 // Allocates and constructs a CClass0SmsUINotifier object |
|
224 CClass0SmsUINotifier* CClass0SmsUINotifier::NewL() |
|
225 { |
|
226 CClass0SmsUINotifier* self=new (ELeave) CClass0SmsUINotifier(); |
|
227 CleanupStack::PushL(self); |
|
228 self->ConstructL(); |
|
229 CleanupStack::Pop(self); |
|
230 return self; |
|
231 } |
|
232 |
|
233 void CClass0SmsUINotifier::ConstructL() |
|
234 { |
|
235 } |
|
236 |
|
237 // destructor |
|
238 CClass0SmsUINotifier::~CClass0SmsUINotifier() |
|
239 { |
|
240 REComSession::FinalClose(); |
|
241 } |
|
242 // constructor |
|
243 CClass0SmsUINotifier::CClass0SmsUINotifier() |
|
244 { |
|
245 //The UID identifying the notifier. |
|
246 iInfo.iUid = KUidClass0SmsNotifier; |
|
247 iInfo.iChannel = KClass0SmsNotifierOutput; |
|
248 iInfo.iPriority = ENotifierPriorityHigh; |
|
249 } |
|
250 |
|
251 // Frees all resources owned by CClass0SmsUINotifier notifier |
|
252 void CClass0SmsUINotifier::Release() |
|
253 { |
|
254 delete this; |
|
255 } |
|
256 |
|
257 |
|
258 // Called when a notifier is first loaded to allow any initial construction that is required. |
|
259 CClass0SmsUINotifier::TNotifierInfo CClass0SmsUINotifier::RegisterL() |
|
260 { |
|
261 return iInfo; |
|
262 } |
|
263 |
|
264 // To get the notifier parameters |
|
265 CClass0SmsUINotifier::TNotifierInfo CClass0SmsUINotifier::Info() const |
|
266 { |
|
267 return iInfo; |
|
268 } |
|
269 |
|
270 |
|
271 // The notifier has been deactivated so resources can be freed and outstanding messages completed. |
|
272 void CClass0SmsUINotifier::Cancel() |
|
273 { |
|
274 } |
|
275 |
|
276 // Class0SMS PDU will be received here. |
|
277 TPtrC8 CClass0SmsUINotifier::StartL(const TDesC8& aBuffer) |
|
278 { |
|
279 ExtractClass0SMSData(aBuffer); |
|
280 return KNullDesC8(); |
|
281 } |
|
282 |
|
283 // Update a currently active notifier with data aBuffer. |
|
284 TPtrC8 CClass0SmsUINotifier::UpdateL(const TDesC8& aBuffer) |
|
285 { |
|
286 ExtractClass0SMSData(aBuffer); |
|
287 return KNullDesC8(); |
|
288 } |
|
289 |
|
290 |
|
291 //Adding ECOM SUPPORT |
|
292 const TImplementationProxy ImplementationTable[] = |
|
293 { |
|
294 IMPLEMENTATION_PROXY_ENTRY(0x2000C612, NotifierArray) |
|
295 }; |
|
296 |
|
297 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) |
|
298 { |
|
299 aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); |
|
300 return ImplementationTable; |
|
301 } |
|
302 |
|
303 // Extract class 0 SMS Message and Display on UI |
|
304 void CClass0SmsUINotifier::ExtractClass0SMSData(const TDesC8& aBuff) |
|
305 { |
|
306 // to extract Starting PDU position of decoded message |
|
307 TInt startPos=0; |
|
308 // to extract Ending PDU position of decoded message |
|
309 TINT endPos=0; |
|
310 // Is it Last message |
|
311 TBool isLastMessage = EFalse; |
|
312 |
|
313 RDesReadStream readStream(aBuff); |
|
314 CleanupClosePushL (readStream); |
|
315 |
|
316 startPos = readStream.ReadInt32L(); |
|
317 endPos = readStream.ReadInt32L(); |
|
318 isLastMessage = readStream.ReadInt32L(); |
|
319 |
|
320 // Buffer to extract SMS data |
|
321 TBuf<1000> smsMsg; |
|
322 readStream >> smsMsg; |
|
323 |
|
324 // function to display SMS Message on UI, this needs to be implemented.. |
|
325 DisplayClass0SMSDataOnUI(smsMsg); |
|
326 } |
|
327 </codeblock> </section> |
|
328 </conbody></concept> |