--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-AA978F65-C25B-59DC-82BC-6892228EA3F9.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,163 @@
+<?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-AA978F65-C25B-59DC-82BC-6892228EA3F9" xml:lang="en"><title>Schedule
+Send Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>Schedule Send MTM (Message Type Module) allows other MTMs to send messages
+at scheduled times. </p>
+<p>This tutorial describes how to schedule SMS sending. For instructions on
+sending SMS messages, see <xref href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita">SMS
+Tutorial</xref>. </p>
+<section><title>Required background</title> <p>Before you start, you must
+understand: </p> <ul>
+<li id="GUID-E818F9A1-74F9-56A2-ADE6-421E3CEFA625"><p><xref href="GUID-33C7EEEB-88B8-5587-916D-2C5D122F6010.dita">SMS
+MTM</xref> </p> </li>
+</ul> </section>
+<section><title>Introduction</title> <p>Scheduled Send MTM enables you to
+do the following tasks: </p> <ul>
+<li id="GUID-7BE42BD7-E4BC-586E-987F-2F7AD54EB1AC"><p>Schedule a message to
+be sent at a specific scheduled time. </p> </li>
+<li id="GUID-E05C56E1-5AB2-50E8-ADD1-F5FEFDA48A3A"><p>Check whether specified
+conditions are met before sending a message. </p> </li>
+<li id="GUID-18AE81ED-E795-55BD-9796-41AAFA43D021"><p>Resend a message if
+an error occurs while sending. </p> </li>
+</ul> <p>An SMS service can have configuration settings which control the
+scheduled sending of messages. These configuration settings are in four parts: </p> <ul>
+<li id="GUID-FE65B7D1-C834-5F38-B766-4CFAA79152AB"><p>General settings: <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> </p> </li>
+<li id="GUID-2E2F2C04-41F4-587D-A222-DFBDC5903AB0"><p>Off-peak times settings: <xref href="GUID-E58A2F58-AF45-3D97-ACA6-6548FE507C3D.dita"><apiname>CMsvOffPeakTimes</apiname></xref>,
+which contains <xref href="GUID-0FAB21AD-16D5-34F4-A8E4-6A75EA02566E.dita"><apiname>TMsvOffPeakTime</apiname></xref> objects </p> </li>
+<li id="GUID-EC741167-6EBD-5E1C-956B-CE1AE755CB67"><p>Send error actions settings: <xref href="GUID-BF841328-372B-3F68-8BC9-5CB8639650D0.dita"><apiname>CMsvSendErrorActions</apiname></xref>,
+which contains <xref href="GUID-4F039FEB-4821-3871-A5CF-0D453BF91EAD.dita"><apiname>TMsvSendErrorAction</apiname></xref> objects </p> </li>
+<li id="GUID-1E957A78-1369-5DAE-9AAD-8A833AC1AA1A"><p>System agent actions
+settings: <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref>, which contains <xref href="GUID-322332B3-5259-3D51-A9AF-CFA2CD5617B6.dita"><apiname>TMsvSysAgentConditionAction</apiname></xref> objects </p> </li>
+</ul> <p>The above settings can be initialised and edited by a client application
+using the following member functions of <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita"><apiname>CSmsAccount</apiname></xref>: </p> <ul>
+<li id="GUID-C724F70C-3299-57DB-9152-5059F398FDC1"><codeblock id="GUID-90932F48-82BA-5D61-A011-3EC155753146" xml:space="preserve">void InitialiseDefaultSettingsL( CMsvScheduleSettings& aScheduleSettings,
+ CMsvOffPeakTimes& aOffPeakTimes,
+ CMsvSendErrorActions& aErrorActions,
+ CMsvSysAgentActions& aSysAgentActions ); </codeblock> </li>
+<li id="GUID-B220B17C-DBEF-56FF-8AC5-A9B760E27660"><codeblock id="GUID-59F2D2ED-0BF3-5802-92FF-F1D93B7CD3F0" xml:space="preserve">void LoadSettingsL( CMsvScheduleSettings& aScheduleSettings,
+ CMsvOffPeakTimes& aOffPeakTimes,
+ CMsvSendErrorActions& aErrorActions,
+ MsvSysAgentActions& aSysAgentActions );</codeblock> </li>
+<li id="GUID-9993E309-541D-58A9-9556-E767848533D3"><codeblock id="GUID-6E50378E-21E6-509B-ABB0-5F1D21F132FA" xml:space="preserve">void SaveSettingsL(const CMsvScheduleSettings& aScheduleSettings,
+ const CMsvOffPeakTimes& aOffPeakTimes,
+ const CMsvSendErrorActions& aErrorActions,
+ const CMsvSysAgentActions& aSysAgentActions ) const;
+ </codeblock> </li>
+</ul> </section>
+<section><title>Procedure</title> <ol id="GUID-8AE541F3-1B0A-5D1D-AA3E-9D56B9513B38">
+<li id="GUID-73A15840-8DC6-5EEE-BCCD-36AE86BC30EC"><p>Create an SMS account
+using the <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita#GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF/GUID-91341F9C-C5DF-35A4-9E09-8EC18A96938A"><apiname>CSmsAccount::NewL()</apiname></xref> function. </p> </li>
+<li id="GUID-9E5F5C1B-D4A3-5A5F-A351-FBDC34CC8F9C"><p>Create an object of <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref> (SMS
+service) and set it with appropriate settings as per your requirement. </p> <note> For
+instructions on creating an SMS account and using the settings APIs, see <xref href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita">SMS Tutorial</xref>. </note> </li>
+<li id="GUID-5125AF39-9039-5257-9260-579ADAEF7AFC"><p>Create an instance of <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> to
+specify general settings for sending a message. </p> </li>
+<li id="GUID-01448B12-C1A7-5E5E-8991-2095363AF338"><p>Load the schedule send
+settings using the <xref href="GUID-31D274E3-CCD9-3948-912A-C3328D507A9A.dita"><apiname>LoadSettingsL()</apiname></xref> function. </p> </li>
+<li id="GUID-BF412FB6-DF4A-5EE9-9BED-5C95FFFD84F8"><p>Save the settings using
+the <xref href="GUID-BBACEDE8-3EB6-3486-996B-1188AF15752C.dita"><apiname>SaveSettingsL()</apiname></xref> function. </p> <p><codeblock id="GUID-9F54ADF1-4015-5D7D-BEA1-F0DDFEB2360D" xml:space="preserve">
+// See SMS tutorial for detailed instructions on the initial set up of SMS, such as message server session,
+// MTM, SMS account and SMS message
+
+ // Create objects for schedule send settings
+
+ CMsvScheduleSettings* scheduleSettings = CMsvScheduleSettings::NewLC();
+ TTimeIntervalSeconds interval(5);
+ scheduleSettings->SetShortInterval(interval);
+
+ // Load the schedule send settings
+ smsAccount->LoadSettingsL(*scheduleSettings, *offPeakTimes);
+
+ // save the settings
+ CSmsAccount *smsAccount = CSmsAccount::NewLC();
+ smsAccount->SaveSettingsL( *scheduleSettings, *offPeakTimes);
+ CleanupStack::PopAndDestroy(); // scheduleSettings, smsAccount</codeblock> </p> </li>
+<li id="GUID-47E51360-87FF-5742-A08F-9653B34BF2B8"><p>Create an SMS message
+and set <xref href="GUID-7D31C4C6-2752-39E5-A789-73AD516F5CBD.dita"><apiname>SetSendingState()</apiname></xref> and <xref href="GUID-895BE1CB-1D52-33A0-B280-485D06088DB2.dita"><apiname>SetScheduled()</apiname></xref>. </p> <p><codeblock id="GUID-D8D7734B-2BA2-5D5E-8A55-11E0F2A75C58" xml:space="preserve">
+ //Create an SMS message (set up index entry)
+ TMsvEntry newEntry;
+ newEntry.iType = KUidMsvMessageEntry;
+ newEntry.iServiceId = KMsvLocalServiceIndexEntryId;
+ newEntry.iMtm = KUidMsgTypeSMS;
+ newEntry.SetVisible(EFalse);
+ newEntry.SetInPreparation(ETrue);
+ newEntry.SetSendingState(KMsvSendStateWaiting);
+ newEntry.SetScheduled(ETrue);</codeblock> </p> </li>
+<li id="GUID-3594C62C-099C-53AE-A9FE-E6F57D7DD3E6"><p>Send the message at
+a specified time. </p> <p>To set a message to be sent at a specified time: </p> <ol id="GUID-B030C1F9-6779-5244-9FDC-611D0F4A8A5E">
+<li id="GUID-4B74937C-8A41-5024-9508-2806245FA2FC"><p>Update the time to send,
+using <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita#GUID-5A23B804-2C06-3407-9D48-1BFB212D699F/GUID-F60F7920-792C-3E53-870F-FC5BFFF84C73"><apiname>TMsvEntry::iDate</apiname></xref>, with the scheduled time. </p> </li>
+<li id="GUID-132F5600-986B-5AE8-A1E1-8F99D646FEEB"><p>Create a selection of
+messages to be sent using <xref href="GUID-6BC8851B-D913-3CE5-B343-5163661E8AD5.dita"><apiname>CMsvEntrySelection</apiname></xref>. </p> <p> Note:
+Every message in the selection must have the same scheduled time. </p> </li>
+<li id="GUID-E725D40B-2806-5D5F-8A5C-49E9AF9281DC"><p>Add the message to the
+selection. </p> </li>
+<li id="GUID-A9AA2EA7-6F52-53CF-8482-1C7E02C88118"><p>Call <xref href="GUID-C499ABDB-BA30-3D97-A850-D5790FE49634.dita#GUID-C499ABDB-BA30-3D97-A850-D5790FE49634/GUID-986D06BF-8427-338A-8EFC-9369E88D62C3"><apiname>CSmsClientMtm::InvokeAsyncFunctionL()</apiname></xref> with
+command ID <codeph>ESmsMtmCommandScheduleCopy</codeph>. </p> </li>
+</ol> <p>The following code snippet schedules a message to be sent in on day’s
+time: </p> <p><codeblock id="GUID-CD68D5F5-3BC3-5B51-A1E4-202233C81ECF" xml:space="preserve">CMsvEntrySelection* smsEntries = new (ELeave) CMsvEntrySelection;
+CleanupStack::PushL(smsEntries);
+TMsvId entryId;
+entryId=newEntry->Id();
+
+// Set the scheduled time for tomorrow
+TTime t;
+t.HomeTime();
+t += TTimeIntervalDays(1);
+newEntry.iDate=t;// update the time to send in the message (TMvsEntry) itself.
+
+// Create a selection of messages to send
+CMsvEntrySelection* smsEntries = new (ELeave) CMsvEntrySelection;
+CleanupStack::PushL(smsEntries);
+
+// Add the newly scheduled message to the selection
+smsEntries->AppendL( newEntry->Id() );
+TBuf8<1> p;
+CMsvOperation* op = iMtm->InvokeAsyncFunctionL(ESmsMtmCommandScheduleCopy,
+*smsEntries, p, iStatus);
+CleanupStack::PopAndDestroy(); //smsEntries
+</codeblock> </p> </li>
+</ol> <note> <ul>
+<li><p>When the scheduled task occurs, not only will the selected messages
+be sent but also any waiting SMS messages in the Outbox.</p></li>
+<li><p>Messages successfully sent by the scheduled task are moved to the Sent
+folder.</p></li>
+</ul></note><p>Messages can be removed from the scheduler using the asynchronous
+function ID <codeph>ESmsMtmCommandDeleteSchedule</codeph>. </p><p><b>Resend
+on errors or failed conditions</b></p><p>A message can be rescheduled at two
+stages of sending: </p><ul>
+<li id="GUID-B3FC8C98-D165-5E7A-B2F5-9D42CDE2807E"><p>If send conditions are
+not met (as seen above): The behaviour when this occurs is configured as part
+of the send actions. </p> </li>
+<li id="GUID-4154A12E-A6D8-5C90-BD0C-AF305BE63BA6"><p>If sending to any recipient
+fails: The behaviour in this event is determined by a <xref href="GUID-86A889FA-CF7F-3B67-9D9E-349E3E0155CC.dita"><apiname>SEND_ERROR_ACTIONS</apiname></xref> resource
+in the SMS Server MTM resource file (in the device ROM). The resource specifies
+the actions that must be taken if errors occur. </p> </li>
+</ul><p>Two additional factors can prevent rescheduling occurring: </p><ul>
+<li id="GUID-6D141526-EB60-53B3-A734-1477CB4372D7"><p>In order to avoid an
+infinite loop of attempting to send a message, which may result in running
+the device battery down, a rescheduled message can be limited to a maximum
+number of re-tries. If the maximum number of re-tries is reached, then the
+message marked as failed and no further retries are attempted. The maximum
+number of re-tries is defined in the <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref> error
+action. </p> </li>
+<li id="GUID-9483768D-B2CA-5616-B789-B6519F5E6826"><p>A timeout can be specified
+for waiting for sending conditions to occur. If the timeout occurs before
+the conditions are met the pending SMS messages are marked as failed. The
+timeout is configurable through the <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita#GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA/GUID-DF0D64F1-5408-335C-8FA8-FE5F874B97E4"><apiname>CMsvScheduleSettings::SetPendingConditionsTimeout()</apiname></xref> function.
+The default is 0 (no timeout). The <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> is
+a separate stream in the SMS service entry store. </p> </li>
+</ul></section>
+<section><title>See also</title> <p><xref href="GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A.dita">Schedule
+Send MTM Overview</xref> </p> </section>
+</conbody></concept>
\ No newline at end of file