<?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-33B590F4-CAE8-58B2-92A9-53123BD42579" xml:lang="en"><title>SMS
Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Short Messaging Service (SMS) provides short text messaging between mobile
phones. Messages can be written and read by phone users. This tutorial demonstrates
the end-to-end procedure for creating and sending SMS messages. </p>

<section><title>Required background</title> <p>Before you start, you must
understand: </p> <ul>
<li id="GUID-784C3290-1D72-5F2F-83FE-E1E85F515B71"><p><xref href="GUID-33C7EEEB-88B8-5587-916D-2C5D122F6010.dita">SMS
MTM</xref>  </p> </li>
<li id="GUID-72E82D46-00A0-5410-B05A-D8B6703B7132"><p><xref href="GUID-CADAABB4-C957-502E-BA4D-E9614C0D3878.dita">Schedule
Send</xref>  </p> </li>
<li id="GUID-CF3038DC-659A-5038-AC70-B6FC6BBF4E52"><p><xref href="GUID-B394A824-8745-505E-8429-8B9B6D418387.dita">Message
Server and Store</xref>  </p> </li>
<li id="GUID-66775375-1A93-522F-B72F-CE353A566CB5"><p><xref href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita">Message
Type Module</xref>  </p> </li>
</ul> </section>

<section><title>Introduction</title> <p>The SMS MTM provides functionality
for creating, storing and sending an SMS message, replying to a received SMS
message and forwarding an existing SMS message. A reply to a received SMS
message may include the original message text, including any EMS components.
Configurable parameters can apply either at a global level or on an individual
message basis. See <xref href="GUID-CBFDD753-BAE3-5C40-B947-EB8CDA11CD23.dita">SMS
concepts</xref> for detailed information on how SMS functionality is implemented
in the Symbian platform. </p> <p>Global settings that are applied to the SMS
MTM are known as SMS service settings. Each SMS message entry has its own
individual group of settings known as SMS message settings. See <xref href="GUID-24414E32-94DC-5870-847B-A797C495F756.dita">SMS
Settings</xref> for more information. </p> <p>This tutorial explains <xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-21F18C1C-F081-5D6A-BD41-B349346AAFF4">how
to create and send messages</xref>. It also explains <xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-CB828B5E-4517-538E-9F20-90AEC17C823A">how to handle incoming messages</xref>. </p> </section>
<section><title>Creating
and sending messages</title> <ol id="GUID-D5EBB762-72EE-5CFA-834D-597CC61FC76C">
<li id="GUID-3E213996-72AA-5860-A5E0-C7F80B2AF7A2"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-AD21D94E-91FA-50D2-B32C-BE4103D97B9B">Get a client MTM object</xref>. </p> </li>
<li id="GUID-3226C878-5EB0-5511-8CD1-31A966CF0618"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-89F63F2A-F868-553F-97AE-F5F207DA33CB">Create a message</xref>. </p> </li>
<li id="GUID-3423C3F4-8CF2-50D7-A57B-BA089C78B171"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-53C7AD41-91B5-5143-B002-C2F8981B9855">Set the message body</xref>. </p> </li>
<li id="GUID-77B95197-7981-5FB9-AD02-726EA90EDACC"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-766E0370-D4B6-55DE-AC30-699665324BD3">Set the message address</xref>. </p> </li>
<li id="GUID-FE9BA0F1-F921-50B7-921B-A0AD5E67F4DF"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-0BD23194-9ED1-5F9B-94B5-EC54678B738B">Set the additional message fields, if required</xref>. </p> </li>
<li id="GUID-183E7CE5-2015-52EC-8D5F-F33E81A51F35"><p><xref href="GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita#GUID-33B590F4-CAE8-58B2-92A9-53123BD42579/GUID-E698D0A6-D312-5759-A2EE-029871BA2076">Send the message</xref>. </p> </li>
</ol><p><b>Get a client MTM object</b></p><p>The Messaging Framework is based
around a server program to which a connection (a session) must be made before
any operation on messaging can be done. The session class is called <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita"><apiname>CMsvSession</apiname></xref>,
and message client applications typically create an instance of this class
upon start-up.</p><codeblock xml:space="preserve">// Create message server sessioniMsvSession = CMsvSession::OpenSyncL(*this);</codeblock><p>The <xref href="GUID-A7121632-37BA-3CDC-AC80-8C6973F59108.dita"><apiname>OpenSyncL()</apiname></xref> method takes a parameter of type <xref href="GUID-BDE23754-4536-3AF7-8549-3B953F51167C.dita"><apiname>MMsvSessionObserver</apiname></xref>.
For this code to work, the containing class must implement this observer interface.
It enables the server to call the client to inform it of significant events,
such as new MTMs being registered. </p> </section>
<section id="GUID-CB828B5E-4517-538E-9F20-90AEC17C823A"><title>Handling incoming
messages </title> <p>Messaging receives SMS messages through a number of watcher
components. When a message is received its contents are read and a new entry
for the message is created in the Message Store (in the global inbox folder).
Typically these messages are then be read by the user through an SMS application,
but other messaging clients can receive notifications when a new message is
created in the store and can process the message if appropriate. </p> <p>To
receive such notifications, a class must implement the <xref href="GUID-BDE23754-4536-3AF7-8549-3B953F51167C.dita"><apiname>MMsvSessionObserver</apiname></xref> session
observer interface. The interface has just one function: </p> <codeblock id="GUID-0F785EE7-2B7D-5864-A5E1-212B0EB0E9A0" xml:space="preserve">void HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* aArg2, TAny* aArg3)=0;</codeblock> <p>When a new message is created in the store, the framework calls this
function with <codeph>aEvent</codeph> set to <codeph>EMsvEntriesCreated</codeph>,
and <codeph>aArg1</codeph> is set to a <codeph>CMsvEntrySelection*</codeph> that
specifies the IDs of the entries that have been created. The following code
snippet checks the event type and gets the entry ID selection: </p> <codeblock id="GUID-9FAAFFD2-AFA2-58B4-9FE4-B0126F1B8BCC" xml:space="preserve">void CClientApp::HandleSessionEventL(TMsvSessionEvent aEvent, TAny* aArg1, TAny* , TAny* )
    {
    CMsvEntrySelection* entries = NULL;

    switch (aEvent)
        {
        case EMsvEntriesCreated:
            entries = static_cast&lt;CMsvEntrySelection*&gt;(aArg1);
            break;
        default:
            break;
        }</codeblock> <p>The observer receives notifications for all types
of entry, so it is necessary to read the message properties to check that
the entry is appropriate to process. </p> <p>The following code snippet does
the first stage of checking: </p> <ol id="GUID-75586A5B-9361-56CA-A18E-879FA38F6D3E">
<li id="GUID-B216D3CF-B462-547A-ABD6-A94696D8545D"><p>Gets the index entry
for the message. Getting an index entry is quick compared to getting the entire
message. Therefore, it is recommended that you perform the required checks
on this first. </p> </li>
<li id="GUID-2B4F2DBA-E443-5F9A-9BD3-23F184E0E475"><p>Tests if the entry is
an SMS message, by checking the index entry's <codeph>iMtm</codeph> and <codeph>iType</codeph> fields </p> </li>
<li id="GUID-3B839895-2DE9-5FD2-A566-23F857800F89"><p>Tests if it is an incoming
message, by checking that the entry is in the Inbox. </p> </li>
</ol> <codeblock id="GUID-DF3AB59E-2391-5A44-9BB9-0E9718562511" xml:space="preserve">if (entries)
    {
    TInt count = entries-&gt;Count();

    // check each entry to see if we want to process it
    while (count--)
        {
        // get the index entry
        TMsvId serviceId;
        TMsvEntry entry;
        iMtm-&gt;Session().GetEntry((*entries)[count], serviceId, entry);
        // if the entry is an SMS message
        if (entry.iMtm == KUidMsgTypeSMS &amp;&amp; entry.iType == KUidMsvMessageEntry
            // and if it's an incoming message (as its in the inbox)
            &amp;&amp; entry.Parent() == KMsvGlobalInBoxIndexEntryId)</codeblock> <p>An
application can now perform further checks, for example, for particular message
content. </p> <codeblock id="GUID-9A15B728-19AD-5869-9D9A-55B0B9E8D4BB" xml:space="preserve">//    sets the client MTM's context to the message 
             
iMtm-&gt;SwitchCurrentEntryL((*entries)[count]);
iMtm-&gt;LoadMessageL();
</codeblock> <p>If you determine that your application must process the message,
you can prevent the user from seeing the message in the Inbox of the standard
messaging application. To do this, you can set the message entry's visible
flag to false using <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita#GUID-5A23B804-2C06-3407-9D48-1BFB212D699F/GUID-05E571D2-785A-37AE-9162-DDED472F7B7B"><apiname>TMsvEntry::SetVisible(EFalse)</apiname></xref>. You
must delete the message once its processing is complete. </p> </section>
<section><title>SMS example</title> <p><xref href="GUID-2D9B17E7-2B7A-5E16-AB06-D9507457A85D.dita">smsexample:
SMS example</xref>  </p> </section>
</conbody><related-links>
<link href="GUID-9AF990D7-C490-5D60-9816-E84B5165A5B2.dita"><linktext>BIO Watcher
Overview</linktext></link>
</related-links></concept>