<?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&amp; aScheduleSettings,
                                    CMsvOffPeakTimes&amp; aOffPeakTimes,
                                    CMsvSendErrorActions&amp; aErrorActions,
                                    CMsvSysAgentActions&amp;  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&amp; aScheduleSettings,
                       CMsvOffPeakTimes&amp; aOffPeakTimes,
                       CMsvSendErrorActions&amp; aErrorActions,
                       MsvSysAgentActions&amp; 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&amp; aScheduleSettings,
                       const CMsvOffPeakTimes&amp; aOffPeakTimes,
                       const CMsvSendErrorActions&amp; aErrorActions,
                       const CMsvSysAgentActions&amp; 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-&gt;SetShortInterval(interval);

    // Load the schedule send settings
    smsAccount-&gt;LoadSettingsL(*scheduleSettings, *offPeakTimes);

    // save the settings 
    CSmsAccount *smsAccount = CSmsAccount::NewLC();
    smsAccount-&gt;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-&gt;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-&gt;AppendL( newEntry-&gt;Id() );
TBuf8&lt;1&gt; p; 
CMsvOperation* op = iMtm-&gt;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>