<?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-F2D86E40-279A-5B48-B91F-922803FEF5DE" xml:lang="en"><title>SMS

MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>SMS MTM provides APIs for sending SMS text messages. This section provides

an overview of the SMS MTM component. </p>

<section id="GUID-6C25C670-C4BF-4BFA-8D3C-D46618AEB5C4"><title>Description</title> <p>The Messaging Application module provides

a SMS MTM for handling SMS messages in the Message Store. For further SMS

support available on the Symbian platform, see <xref href="GUID-34E7AAF2-EC62-5BF6-B9E7-C7D346BCDF93.dita">Cellular

Baseband Services Guide</xref> documentation. </p> <p><b>Supported functionality</b> </p> <p>SMS

MTM provides functionality to create, store and retrieve an SMS message entry

in the Message Store, send an SMS, reply to a received SMS and forward existing

SMS. A reply to a received SMS may include the original message text, including

any EMS components. </p> <p>SMS that are received by SMS MTM are stored in

the Message Store. The type and class of the received SMS affects the storage

of a message. All received class 2 SMS are stored in a non-Symbian platform

store. </p> <p><b>Storing SMS</b> </p> <p>SMS messages that are received by

SMS MTM are stored in both the Message Store and a non-Symbian platform store.

Messages can be moved, copied to, from the non-Symbian platform store and

the Message Store. The non-Symbian platform store can be enumerated so that

its contents can be reflected in the folder in the Message Store, except any

of the standard folders (for example, the global inbox). </p> <p>The type

and class of the received SMS affects message storage. All received class

2 SMS message are stored in the class 2 folder in a non-Symbian platform store.

The class 2 folder is a configurable location in the Message Store and may

be set to be the global inbox. All received non-class 2 SMS messages are stored

in the global inbox folder of the Message Store. </p> <p><b>Sending SMS</b> </p> <p>SMS

MTM can send the message immediately or schedule it for a specific time. Before

SMS MTM sends an SMS, it checks the global outbox in the Message Store for

any SMS that are waiting to be sent (these can also be scheduled for sending).

If an SMS failed to be sent, then the MTM may re-schedule that SMS to be sent

at a later time. A re-schedule is configurable against the failure error code.

The schedule send functionality handles this configuration. A SMS that is

successfully sent is moved to the sent folder in the Message Store by SMS

MTM. </p> <p>This MTM supports multiple recipients for an SMS message. An

outgoing SMS message may have multiple recipients. When this message is being

sent, one message is sent for each recipient. </p> <p><b>BIO messages</b> </p> <p>SMS

MTM is aware of BIO messages and uses the BIO Framework to tag SMS with the

appropriate BIO type. This includes support for WAP messages. </p> <p><b>Unsupported

functionality</b> </p> <p>SMS MTM does not support sending and receiving OTA

(Over The Air) SMS messages. </p> </section>

<section id="GUID-9776B05D-D289-46C0-83C0-BD30E82A65EC"><title>Architecture</title> <p>The Messaging Middleware architecture

defines a framework in which modules (MTMs) can be implemented that provide

support for particular messaging protocols. A client MTM provides the API

for application engines to use the protocol. SMS MTM API provides the client

MTM API, server MTM API, and supporting classes for SMS. </p> <p>SMS MTM integrates

SMS into the Messaging architecture, so that SMS can be used by a messaging

client program in a similar way to other message types such as email. SMS

MTM uses the SMS interface provided by the Telephony sub-system. This provides

support for 7, 8, and 16-bit text messages, and message concatenation. </p> <p>The

following figure shows the SMS architecture:</p> <fig id="GUID-F904EC3A-7292-5A57-BC4E-1C736D24223C">

<title>              SMS MTM architecture            </title>

<image href="GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e270252_href.jpg" placement="inline"/>

</fig> <p><b>SMS Client MTM</b> </p> <p>The SMS Client MTM implements the

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

MTM APIs</xref> described in <xref href="GUID-E180D222-CC4F-5007-93FC-C339BBE708BC.dita">Client

MTM</xref>. In addition, it provides the following functionality: </p> <ul>

<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

that is used to represent the SMS message. </p> </li>

<li id="GUID-DEDCDE66-84B8-596C-AA2B-0D3E89AF2656"><p>Access to the SMS settings

stored in the associated SMS service centre. </p> </li>

<li id="GUID-5FEEE0B8-E58F-5E7A-9A6E-5AD4FB206192"><p>Provides the APIs required

by SendAs to allow SendAs to create SMS, including setting the BIO type message

to allow clients of SendAs to send BIO messages, such as vCards and vCals.

The data of the BIO message is stored in the body text of the SMS. </p> </li>

<li id="GUID-DF695D34-951B-5B21-8D95-5ACF2699A57B"><p>Simple check for valid

SMS addresses; an SMS address is considered valid if it contains at least

one digit. </p> </li>

<li id="GUID-CBDDD0E5-8BDE-579E-B52F-7DFC40926B07"><p>Reading and writing

SIM parameters. </p> </li>

</ul><note> MS receiving is normally done automatically by the Cellular Baseband

and messaging components, with received SMS messages placed in the Inbox.

Generic message receiving operations are not supported by the MTM. Also, UI

functionality, such as SMS message viewing and editing, is not provided by

the 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

Server MTM implements the <xref href="GUID-963C0F50-A44A-518E-8DB0-42BEBEFD10A2.dita">Server-side

MTM</xref> interface, and primarily provides functionality to handle requests

from the client MTM to send SMS messages. Incoming SMS messages are handled

by a group of components called SMS watchers. </p> <p>These components provide

a layer over the SMS support provided in the Narrow Band Protocols Stack subsystem.

This has SMS stacks for GSM which offer an encapsulation of an SMS message,

together with the ability to send and receive messages. At the lowest level,

below the SMS stacks, is the ETel multimode API, which provides low-level

access to the phone drivers. </p> <p>The SMS Server MTM provides access to

messages under remote services. It is loaded in the Message Server’s process

space and handles the following tasks: </p> <ul>

<li id="GUID-F4EE3024-0E25-5628-BABA-FA3D040844B3"><p>Connecting to remote

servers to handle updating the cache of SMS messages. </p> </li>

<li id="GUID-9E768517-6189-59DD-93D4-66EA4DC491CD"><p>Sending messages that

are copied to remote services when messages are copied to a remote service. </p> <p>The

SMS Server MTM handles sending of SMS and WAP messages through the SMS stack

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

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

MTM base class</xref>. It implements this for sending SMS and moving the successfully

sent messages to the <b>Sent</b> folder. When sending the SMS, the Server

MTM checks the BIO type of the message and uses the BIO database to check

the transport type for the BIO message. The MTM supports <codeph>ENbs</codeph> that

is sent through the SMS stack and <codeph>EWap</codeph>, <codeph>EWapSecure</codeph> that

are sent through the WAP stack. The MTM does not support <codeph>EWsp</codeph> or <codeph>EWspSecure</codeph> although

the watchers do support receiving them. </p> </li>

<li id="GUID-8086B93E-6AC2-5BFD-97E4-C95538B4C821"><p>Scheduling messages </p> <p>The

SMS Server MTM implements scheduled sending API by sub-classing from the Schedule

send Server MTM. It accepts requests from client applications either through

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

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

messages to be sent or to delete existing schedules. When it receives a request

to schedule a message, it packages the command and uses the Scheduled Send

functionality to request that the task scheduler ask it to send the messages

at a future point in time. </p> </li>

<li id="GUID-BE3E335F-900E-5C7A-A5AE-CDCD1DEEF5FE"><p>Managing phone store </p> <p>The

phone store is a storage for SMS outside the Message Store. For example, for

GSM phones it is the <b>SIM</b>. The SMS Server MTM accepts requests from

client applications to copy or move messages to and from the SIM and delete

messages from the SIM. For example, when copying to the SIM, it packages SMS

and passes it to the SMS stack with a request to write it to the SIM. If the

class2 folder is set in the SMS settings class, the Server MTM copies the

SMS to the SIM and then updates the SMS in the message store. The Server MTM

also provides the details of the space used to store on the SIM and the reason

for storing on the SIM. </p> </li>

<li id="GUID-096F78F8-44B0-5F35-84C7-ED6E312C2E60"><p>Providing SIM parameters </p> <p>The

Server MTM provides functions to read and write SIM parameters. </p> </li>

</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

Utilities</b> </p> <p>SMS Utilities provide the following: </p> <ul>

<li id="GUID-09858DED-EBC8-5C22-AB67-E1F20ECE617A"><p>Classes to represent

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>)

and a SMS number (<xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref>). </p> </li>

<li id="GUID-8B55A758-1104-5C58-A428-4DD7F2562DB9"><p>Functions to generate

descriptions and details fields to store with SMS. The details includes decoding

special messages (such as, message indication and status report messages),

reading resource file for descriptions strings of special messages, and using

the contacts database to replace phone numbers with names. </p> </li>

<li id="GUID-5F410D35-D654-5CBC-8E52-6E6400D929B1"><p>Function to validate

a GSM number. </p> </li>

<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

the SMS service entry. </p> </li>

</ul> <p><b>SMS Watchers</b> </p> <p>SMS Watchers are made up of two watchers,

the <filepath>nbswatcher.dll</filepath> and the <filepath>wapwatcher.dll</filepath>,

and some common base classes in <filepath>biowatcher.dll</filepath>. The watchers

listen for incoming messages from the SMS Stack, part of Cellular Baseband

Services, and the WAP stack, part of High-level Internet Protocols. </p> <p><b>SMS

Stack</b> </p> <p>SMS Stack is one of a number of protocol stacks that is

supported by the ESock Server client-server framework. The SMS Stack’s principal

clients are the messaging applications, WAP Stack and third party applications.

The Messaging Application and the third party applications access the stack

as clients of the ESock Server, while the WAP Stack accesses directly the

SMS Stack. For more information on SMS Stack, see <xref href="GUID-E0DA7DE7-FD5A-5C1D-A53C-870966F00445.dita">SMS

Stack for GSM Networks</xref>. </p> <p><b>SMS service settings</b> </p> <p>Settings

for SMS connections, such as service centre addresses, are stored in the Message

Store (<xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita"><apiname>CMsvStore</apiname></xref>) for the SMS service entry. Encapsulation

of service settings is provided by <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref>. </p> <p><b>Progress

information</b> </p> <p>The progress information can be obtained for messaging

operations. For SMS operations, progress information includes such things

as type of operation, and number of messages processed. Progress information

is provided by <xref href="GUID-25FA6A20-1122-3B06-B8AF-59D3FDBDDC76.dita"><apiname>TSmsProgress</apiname></xref>. </p> </section>

<section id="GUID-80A5C81E-42C9-4432-A97D-872525E5D468"><title>APIs</title> <fig id="GUID-EABD829F-612D-53DF-BFDF-1F4E27FD4FD8">

<image href="GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e270526_href.jpg" placement="inline"/>

</fig> <p>The following are the important classes for SMS Client MTM: </p> <table id="GUID-8C815D5D-0494-5507-8A7D-275641BFF71D">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Class</b>  </p> </entry>

<entry><p> <b>Purpose</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-C499ABDB-BA30-3D97-A850-D5790FE49634.dita"><apiname>CSmsClientMtm</apiname></xref>  </p> </entry>

<entry><p>Implements the messaging architecture client MTM interface for SMS.

It allows messages to be created, replied to, and forwarded, and MTM-specific

commands to be given. </p> <p>It provides an accessor function <codeph>SmsHeader()</codeph> to

get the <codeph>CSmsHeader</codeph> for a message. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-790D9BA9-2FB7-3073-AF2F-FFD049C3FD3D.dita"><apiname>CSmsHeader</apiname></xref>  </p> </entry>

<entry><p>Encapsulates an SMS message in a message store. </p> <p>It provides

information about message recipients as an array of <xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref> objects,

and access to the family of classes derived from <xref href="GUID-A57B70F4-3F29-31AC-9763-FE5DE25E85CC.dita"><apiname>TMsvMessageBio</apiname></xref>,

which allow fields of a message to be set and accessed. </p> <p>For compatibility

with the API of the v8 (GSM only) SMS MTM, it also provides access to the

GSM SMS stack's message class <xref href="GUID-FA6D9B1B-3845-3B81-ACBB-34977D3C9631.dita"><apiname>CSmsMessage</apiname></xref>. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-ABF26927-F794-39D1-97B2-C7CD447224DF.dita"><apiname>TMsvMessageGsm</apiname></xref>  </p> </entry>

<entry><p>Provides access to GSM-specific fields. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-920DFEAD-41A4-3586-98F0-BA0FEEC2FD13.dita"><apiname>TMsvSmsEntry</apiname></xref>  </p> </entry>

<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

SMS message entries. </p> <p>Putting selected SMS-specific fields in the index

entry allows message clients to quickly get important message properties without

having to create a message object. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-6DB3A42E-14FC-3B87-AB8E-7C05CA34B3AB.dita"><apiname>CSmsNumber</apiname></xref>  </p> </entry>

<entry><p>Encapsulates recipient information for an SMS message. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref>  </p> </entry>

<entry><p>Defines settings for the SMS service. </p> <p>It contains some GSM-specific

functions to maintain compability with the GSM SMS MTM. </p> <p>It also provides

access to <xref href="GUID-CFD9E5F2-F28F-3A95-A53A-34030345EAF9.dita"><apiname>CSmsMessageSettingsProxy</apiname></xref> for outgoing message

defaults. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita"><apiname>CSmsAccount</apiname></xref>  </p> </entry>

<entry><p>Stores SMS service and Schedule Send settings to Central Repository. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9BD25A7F-4A9E-3469-BA7F-F016E2ED8BFC.dita"><apiname>CSmsServiceCenter</apiname></xref>  </p> </entry>

<entry><p>Used to store Service Centre numbers and their associated name. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

</conbody><related-links>

<link href="GUID-69438F28-E2E9-5BFA-B644-08FB59D50A39.dita"><linktext>SMS MTM Concepts</linktext>

</link>

<link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type

Module</linktext></link>

<link href="GUID-E56E21A9-B545-5217-A877-E64D30275157.dita"><linktext>Using the

Policy Evaluator Plug-in</linktext></link>

<link href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita"><linktext>SMS     

           Tutorial</linktext></link>