--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-33B590F4-CAE8-58B2-92A9-53123BD42579.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,123 @@
+<?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>
\ No newline at end of file