|
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-F2D86E40-279A-5B48-B91F-922803FEF5DE" xml:lang="en"><title>SMS |
|
13 MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>SMS MTM provides APIs for sending SMS text messages. This section provides |
|
15 an overview of the SMS MTM component. </p> |
|
16 <section><title>Description</title> <p>The Messaging Application module provides |
|
17 a SMS MTM for handling SMS messages in the Message Store. For further SMS |
|
18 support available the Symbian platform, see <xref href="GUID-34E7AAF2-EC62-5BF6-B9E7-C7D346BCDF93.dita">Cellular |
|
19 Baseband Services Guide</xref> documentation. </p> <p><b>Supported functionality</b> </p> <p>SMS |
|
20 MTM provides functionality to create, store and retrieve an SMS message entry |
|
21 in the Message Store, send an SMS, reply to a received SMS and forward existing |
|
22 SMS. A reply to a received SMS may include the original message text, including |
|
23 any EMS components. </p> <p>SMS that are received by SMS MTM are stored in |
|
24 the Message Store. The type and class of the received SMS affects the storage |
|
25 of a message. All received class 2 SMS are stored in a non-Symbian platform |
|
26 store. </p> <p><b>Storing SMS</b> </p> <p>SMS messages that are received by |
|
27 SMS MTM are stored in both the Message Store and a non-Symbian platform store. |
|
28 Messages can be moved, copied to, from the non-Symbian platform store and |
|
29 the Message Store. The non-Symbian platform store can be enumerated so that |
|
30 its contents can be reflected in the folder in the Message Store, except any |
|
31 of the standard folders (for example, the global inbox). </p> <p>The type |
|
32 and class of the received SMS affects message storage. All received class |
|
33 2 SMS message are stored in the class 2 folder in a non-Symbian platform store. |
|
34 The class 2 folder is a configurable location in the Message Store and may |
|
35 be set to be the global inbox. All received non-class 2 SMS messages are stored |
|
36 in the global inbox folder of the Message Store. </p> <p><b>Sending SMS</b> </p> <p>SMS |
|
37 MTM can send the message immediately or schedule it for a specific time. Before |
|
38 SMS MTM sends an SMS, it checks the global outbox in the Message Store for |
|
39 any SMS that are waiting to be sent (these can also be scheduled for sending). |
|
40 If an SMS failed to be sent, then the MTM may re-schedule that SMS to be sent |
|
41 at a later time. A re-schedule is configurable against the failure error code. |
|
42 The schedule send functionality handles this configuration. A SMS that is |
|
43 successfully sent is moved to the sent folder in the Message Store by SMS |
|
44 MTM. </p> <p>This MTM supports multiple recipients for an SMS message. An |
|
45 outgoing SMS message may have multiple recipients. When this message is being |
|
46 sent, one message is sent for each recipient. </p> <p><b>BIO messages</b> </p> <p>SMS |
|
47 MTM is aware of BIO messages and uses the BIO Framework to tag SMS with the |
|
48 appropriate BIO type. This includes support for WAP messages. </p> <p><b>Unsupported |
|
49 functionality</b> </p> <p>SMS MTM does not support sending and receiving OTA |
|
50 (Over The Air) SMS messages. </p> </section> |
|
51 <section><title>Architecture</title> <p>The Messaging Middleware architecture |
|
52 defines a framework in which modules (MTMs) can be implemented that provide |
|
53 support for particular messaging protocols. A client MTM provides the API |
|
54 for application engines to use the protocol. SMS MTM API provides the client |
|
55 MTM API, server MTM API, and supporting classes for SMS. </p> <p>SMS MTM integrates |
|
56 SMS into the Messaging architecture, so that SMS can be used by a messaging |
|
57 client program in a similar way to other message types such as email. SMS |
|
58 MTM uses the SMS interface provided by the Telephony sub-system. This provides |
|
59 support for 7, 8, and 16-bit text messages, and message concatenation. </p> <p>The |
|
60 following figure shows the SMS architecture that Symbian has implemented in |
|
61 the Symbian platform. </p> <fig id="GUID-F904EC3A-7292-5A57-BC4E-1C736D24223C"> |
|
62 <title> SMS MTM architecture </title> |
|
63 <image href="GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e245297_href.jpg" placement="inline"/> |
|
64 </fig> <p><b>SMS Client MTM</b> </p> <p>The SMS Client MTM implements the |
|
65 standard set of <xref href="GUID-E180D222-CC4F-5007-93FC-C339BBE708BC.dita#GUID-E180D222-CC4F-5007-93FC-C339BBE708BC/GUID-BCFBE2C5-2C90-5E43-9B21-0D80A469CEAB">Client |
|
66 MTM APIs</xref> described in <xref href="GUID-E180D222-CC4F-5007-93FC-C339BBE708BC.dita">Client |
|
67 MTM</xref>. In addition, it provides the following functionality: </p> <ul> |
|
68 <li id="GUID-8044B9F8-BF51-577B-B99A-7E7598172DD7"><p>Access to the <xref href="GUID-790D9BA9-2FB7-3073-AF2F-FFD049C3FD3D.dita"><apiname>CSmsHeader</apiname></xref> object |
|
69 that is used to represent the SMS message. </p> </li> |
|
70 <li id="GUID-DEDCDE66-84B8-596C-AA2B-0D3E89AF2656"><p>Access to the SMS settings |
|
71 stored in the associated SMS service centre. </p> </li> |
|
72 <li id="GUID-5FEEE0B8-E58F-5E7A-9A6E-5AD4FB206192"><p>Provides the APIs required |
|
73 by SendAs to allow SendAs to create SMS, including setting the BIO type message |
|
74 to allow clients of SendAs to send BIO messages, such as vCards and vCals. |
|
75 The data of the BIO message is stored in the body text of the SMS. </p> </li> |
|
76 <li id="GUID-DF695D34-951B-5B21-8D95-5ACF2699A57B"><p>Simple check for valid |
|
77 SMS addresses; an SMS address is considered valid if it contains at least |
|
78 one digit. </p> </li> |
|
79 <li id="GUID-CBDDD0E5-8BDE-579E-B52F-7DFC40926B07"><p>Reading and writing |
|
80 SIM parameters. </p> </li> |
|
81 </ul><note> MS receiving is normally done automatically by the Cellular Baseband |
|
82 and messaging components, with received SMS messages placed in the Inbox. |
|
83 Generic message receiving operations are not supported by the MTM. Also, UI |
|
84 functionality, such as SMS message viewing and editing, is not provided by |
|
85 Symbian platform.</note> <p>The SMS Client MTM class is <xref href="GUID-C499ABDB-BA30-3D97-A850-D5790FE49634.dita"><apiname>CSmsClientMtm</apiname></xref>. </p> <p id="GUID-752B2A3B-CC1D-50CB-B3BF-113BED635538"><b>SMS Server MTM</b> </p> <p>SMS |
|
86 Server MTM implements the <xref href="GUID-963C0F50-A44A-518E-8DB0-42BEBEFD10A2.dita">Server-side |
|
87 MTM</xref> interface, and primarily provides functionality to handle requests |
|
88 from the client MTM to send SMS messages. Incoming SMS messages are handled |
|
89 by a group of components called SMS watchers. </p> <p>These components provide |
|
90 a layer over the SMS support provided in the Narrow Band Protocols Stack subsystem. |
|
91 This has SMS stacks for GSM which offer an encapsulation of an SMS message, |
|
92 together with the ability to send and receive messages. At the lowest level, |
|
93 below the SMS stacks, is the ETel multimode API, which provides low-level |
|
94 access to the phone drivers. </p> <p>The SMS Server MTM provides access to |
|
95 messages under remote services. It is loaded in the Message Server’s process |
|
96 space and handles the following tasks: </p> <ul> |
|
97 <li id="GUID-F4EE3024-0E25-5628-BABA-FA3D040844B3"><p>Connecting to remote |
|
98 servers to handle updating the cache of SMS messages. </p> </li> |
|
99 <li id="GUID-9E768517-6189-59DD-93D4-66EA4DC491CD"><p>Sending messages that |
|
100 are copied to remote services when messages are copied to a remote service. </p> <p>The |
|
101 SMS Server MTM handles sending of SMS and WAP messages through the SMS stack |
|
102 and the WAP stack respectively. To support this, it implements the <xref href="GUID-D088273D-FAFE-30F6-8D0A-3A62D3DE62FD.dita#GUID-D088273D-FAFE-30F6-8D0A-3A62D3DE62FD/GUID-46569C6B-0F24-392E-A649-091D91BAE910"><apiname>CBaseServerMtm::CopyFromLocal()</apiname></xref> function |
|
103 inherited from the <xref href="GUID-963C0F50-A44A-518E-8DB0-42BEBEFD10A2.dita#GUID-963C0F50-A44A-518E-8DB0-42BEBEFD10A2/GUID-54184D61-6325-525D-947F-D86EF8072BFC">Server |
|
104 MTM base class</xref>. It implements this for sending SMS and moving the successfully |
|
105 sent messages to the <b>Sent</b> folder. When sending the SMS, the Server |
|
106 MTM checks the BIO type of the message and uses the BIO database to check |
|
107 the transport type for the BIO message. The MTM supports <codeph>ENbs</codeph> that |
|
108 is sent through the SMS stack and <codeph>EWap</codeph>, <codeph>EWapSecure</codeph> that |
|
109 are sent through the WAP stack. The MTM does not support <codeph>EWsp</codeph> or <codeph>EWspSecure</codeph> although |
|
110 the watchers do support receiving them. </p> </li> |
|
111 <li id="GUID-8086B93E-6AC2-5BFD-97E4-C95538B4C821"><p>Scheduling messages </p> <p>The |
|
112 SMS Server MTM implements scheduled sending API by sub-classing from the Schedule |
|
113 send Server MTM. It accepts requests from client applications either through |
|
114 the SMS Client MTM's <xref href="GUID-177AF50B-14EF-3C45-AE22-1FEE5678261D.dita#GUID-177AF50B-14EF-3C45-AE22-1FEE5678261D/GUID-05327221-98A9-35FA-BD28-D6323BE449D1"><apiname>CBaseMtm::InvokeAsyncFunctionL()</apiname></xref> API |
|
115 or through the <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita#GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B/GUID-43563010-9B4F-31EB-BE83-E7C4C1979677"><apiname>CMsvSession::TransferCommand()</apiname></xref> API to schedule |
|
116 messages to be sent or to delete existing schedules. When it receives a request |
|
117 to schedule a message, it packages the command and uses the Scheduled Send |
|
118 functionality to request that the task scheduler ask it to send the messages |
|
119 at a future point in time. </p> </li> |
|
120 <li id="GUID-BE3E335F-900E-5C7A-A5AE-CDCD1DEEF5FE"><p>Managing phone store </p> <p>The |
|
121 phone store is a storage for SMS outside the Message Store. For example, for |
|
122 GSM phones it is the <b>SIM</b>. The SMS Server MTM accepts requests from |
|
123 client applications to copy or move messages to and from the SIM and delete |
|
124 messages from the SIM. For example, when copying to the SIM, it packages SMS |
|
125 and passes it to the SMS stack with a request to write it to the SIM. If the |
|
126 class2 folder is set in the SMS settings class, the Server MTM copies the |
|
127 SMS to the SIM and then updates the SMS in the message store. The Server MTM |
|
128 also provides the details of the space used to store on the SIM and the reason |
|
129 for storing on the SIM. </p> </li> |
|
130 <li id="GUID-096F78F8-44B0-5F35-84C7-ED6E312C2E60"><p>Providing SIM parameters </p> <p>The |
|
131 Server MTM provides functions to read and write SIM parameters. </p> </li> |
|
132 </ul> <p>The SMS Server MTM class is <xref href="GUID-1CC9D9DD-4C6A-3B71-8006-E0289E4C8C62.dita"><apiname>CSmsServerMtm</apiname></xref>. </p> <p><b>SMS |
|
133 Utilities</b> </p> <p>SMS Utilities provide the following: </p> <ul> |
|
134 <li id="GUID-09858DED-EBC8-5C22-AB67-E1F20ECE617A"><p>Classes to represent |
|
135 and store SMS (<xref href="GUID-790D9BA9-2FB7-3073-AF2F-FFD049C3FD3D.dita"><apiname>CSmsHeader</apiname></xref>), and SMS settings (<xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref>, <xref href="GUID-D96E6D26-0D1A-36B4-85E1-63DA127F099A.dita"><apiname>CSmsMessageSettings</apiname></xref>) |
|
136 and a SMS number (<xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref>). </p> </li> |
|
137 <li id="GUID-8B55A758-1104-5C58-A428-4DD7F2562DB9"><p>Functions to generate |
|
138 descriptions and details fields to store with SMS. The details includes decoding |
|
139 special messages (such as, message indication and status report messages), |
|
140 reading resource file for descriptions strings of special messages, and using |
|
141 the contacts database to replace phone numbers with names. </p> </li> |
|
142 <li id="GUID-5F410D35-D654-5CBC-8E52-6E6400D929B1"><p>Function to validate |
|
143 a GSM number. </p> </li> |
|
144 <li id="GUID-2C531B06-90D4-5F75-BD85-60330DCBE81C"><p>Mode to find the <xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> of |
|
145 the SMS service entry. </p> </li> |
|
146 </ul> <p><b>SMS Watchers</b> </p> <p>SMS Watchers are made up of two watchers, |
|
147 the <filepath>nbswatcher.dll</filepath> and the <filepath>wapwatcher.dll</filepath>, |
|
148 and some common base classes in <filepath>biowatcher.dll</filepath>. The watchers |
|
149 listen for incoming messages from the SMS Stack, part of Cellular Baseband |
|
150 Services, and the WAP stack, part of High-level Internet Protocols. </p> <p><b>SMS |
|
151 Stack</b> </p> <p>SMS Stack is one of a number of protocol stacks that is |
|
152 supported by the ESock Server client-server framework. The SMS Stack’s principal |
|
153 clients are the messaging applications, WAP Stack and third party applications. |
|
154 The Messaging Application and the third party applications access the stack |
|
155 as clients of the ESock Server, while the WAP Stack accesses directly the |
|
156 SMS Stack. For more information on SMS Stack, see <xref href="GUID-E0DA7DE7-FD5A-5C1D-A53C-870966F00445.dita">SMS |
|
157 Stack for GSM Networks</xref>. </p> <p><b>SMS service settings</b> </p> <p>Settings |
|
158 for SMS connections, such as service centre addresses, are stored in the Message |
|
159 Store (<xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita"><apiname>CMsvStore</apiname></xref>) for the SMS service entry. Encapsulation |
|
160 of service settings is provided by <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref>. </p> <p><b>Progress |
|
161 information</b> </p> <p>The progress information can be obtained for messaging |
|
162 operations. For SMS operations, progress information includes such things |
|
163 as type of operation, and number of messages processed. Progress information |
|
164 is provided by <xref href="GUID-25FA6A20-1122-3B06-B8AF-59D3FDBDDC76.dita"><apiname>TSmsProgress</apiname></xref>. </p> </section> |
|
165 <section><title>APIs</title> <fig id="GUID-EABD829F-612D-53DF-BFDF-1F4E27FD4FD8"> |
|
166 <image href="GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e245569_href.jpg" placement="inline"/> |
|
167 </fig> <p>The following are the important classes for SMS Client MTM: </p> <table id="GUID-8C815D5D-0494-5507-8A7D-275641BFF71D"> |
|
168 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
169 <tbody> |
|
170 <row> |
|
171 <entry><p> <b>Class</b> </p> </entry> |
|
172 <entry><p> <b>Purpose</b> </p> </entry> |
|
173 </row> |
|
174 <row> |
|
175 <entry><p> <xref href="GUID-C499ABDB-BA30-3D97-A850-D5790FE49634.dita"><apiname>CSmsClientMtm</apiname></xref> </p> </entry> |
|
176 <entry><p>Implements the messaging architecture client MTM interface for SMS. |
|
177 It allows messages to be created, replied to, and forwarded, and MTM-specific |
|
178 commands to be given. </p> <p>It provides an accessor function <codeph>SmsHeader()</codeph> to |
|
179 get the <codeph>CSmsHeader</codeph> for a message. </p> </entry> |
|
180 </row> |
|
181 <row> |
|
182 <entry><p> <xref href="GUID-790D9BA9-2FB7-3073-AF2F-FFD049C3FD3D.dita"><apiname>CSmsHeader</apiname></xref> </p> </entry> |
|
183 <entry><p>Encapsulates an SMS message in a message store. </p> <p>It provides |
|
184 information about message recipients as an array of <xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref> objects, |
|
185 and access to the family of classes derived from <xref href="GUID-A57B70F4-3F29-31AC-9763-FE5DE25E85CC.dita"><apiname>TMsvMessageBio</apiname></xref>, |
|
186 which allow fields of a message to be set and accessed. </p> <p>For compatibility |
|
187 with the API of the v8 (GSM only) SMS MTM, it also provides access to the |
|
188 GSM SMS stack's message class <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita"><apiname>CSmsMessage</apiname></xref>. </p> </entry> |
|
189 </row> |
|
190 <row> |
|
191 <entry><p> <xref href="GUID-ABF26927-F794-39D1-97B2-C7CD447224DF.dita"><apiname>TMsvMessageGsm</apiname></xref> </p> </entry> |
|
192 <entry><p>Provides access to GSM-specific fields. </p> </entry> |
|
193 </row> |
|
194 <row> |
|
195 <entry><p> <xref href="GUID-920DFEAD-41A4-3586-98F0-BA0FEEC2FD13.dita"><apiname>TMsvSmsEntry</apiname></xref> </p> </entry> |
|
196 <entry><p>Provides a specialisation of the message server index class <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> for |
|
197 SMS message entries. </p> <p>Putting selected SMS-specific fields in the index |
|
198 entry allows message clients to quickly get important message properties without |
|
199 having to create a message object. </p> </entry> |
|
200 </row> |
|
201 <row> |
|
202 <entry><p> <xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref> </p> </entry> |
|
203 <entry><p>Encapsulates recipient information for an SMS message. </p> </entry> |
|
204 </row> |
|
205 <row> |
|
206 <entry><p> <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref> </p> </entry> |
|
207 <entry><p>Defines settings for the SMS service. </p> <p>It contains some GSM-specific |
|
208 functions to maintain compability with the GSM SMS MTM. </p> <p>It also provides |
|
209 access to <xref href="GUID-CFD9E5F2-F28F-3A95-A53A-34030345EAF9.dita"><apiname>CSmsMessageSettingsProxy</apiname></xref> for outgoing message |
|
210 defaults. </p> </entry> |
|
211 </row> |
|
212 <row> |
|
213 <entry><p> <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita"><apiname>CSmsAccount</apiname></xref> </p> </entry> |
|
214 <entry><p>Stores SMS service and Schedule Send settings to Central Repository. </p> </entry> |
|
215 </row> |
|
216 <row> |
|
217 <entry><p> <xref href="GUID-9BD25A7F-4A9E-3469-BA7F-F016E2ED8BFC.dita"><apiname>CSmsServiceCenter</apiname></xref> </p> </entry> |
|
218 <entry><p>Used to store Service Centre numbers and their associated name. </p> </entry> |
|
219 </row> |
|
220 </tbody> |
|
221 </tgroup> |
|
222 </table> </section> |
|
223 </conbody><related-links> |
|
224 <link href="GUID-69438F28-E2E9-5BFA-B644-08FB59D50A39.dita"><linktext>SMS MTM Concepts</linktext> |
|
225 </link> |
|
226 <link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type |
|
227 Module</linktext></link> |
|
228 <link href="GUID-E56E21A9-B545-5217-A877-E64D30275157.dita"><linktext>Using the |
|
229 Policy Evaluator Plug-in</linktext></link> |
|
230 <link href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita"><linktext>SMS |
|
231 Tutorial</linktext></link> |
|
232 </related-links></concept> |