<?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<CMsvEntrySelection*>(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->Count();

    // check each entry to see if we want to process it

    while (count--)

        {

        // get the index entry

        TMsvId serviceId;

        TMsvEntry entry;

        iMtm->Session().GetEntry((*entries)[count], serviceId, entry);

        // if the entry is an SMS message

        if (entry.iMtm == KUidMsgTypeSMS && 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->SwitchCurrentEntryL((*entries)[count]);

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