Schedule +Send Tutorial

Schedule Send MTM (Message Type Module) allows other MTMs to send messages +at scheduled times.

This tutorial describes how to schedule SMS sending. For instructions on +sending SMS messages, see SMS +Tutorial.

Introduction

Scheduled Send MTM enables you to +do the following tasks:

Schedule a message to +be sent at a specific scheduled time.
Check whether specified +conditions are met before sending a message.
Resend a message if +an error occurs while sending.

An SMS service can have configuration settings which control the +scheduled sending of messages. These configuration settings are in four parts:

General settings: CMsvScheduleSettings
Off-peak times settings: CMsvOffPeakTimes, +which contains TMsvOffPeakTime objects
Send error actions settings: CMsvSendErrorActions, +which contains TMsvSendErrorAction objects
System agent actions +settings: CMsvSysAgentActions, which contains TMsvSysAgentConditionAction objects

The above settings can be initialised and edited by a client application +using the following member functions of CSmsAccount:

void InitialiseDefaultSettingsL( CMsvScheduleSettings& aScheduleSettings, + CMsvOffPeakTimes& aOffPeakTimes, + CMsvSendErrorActions& aErrorActions, + CMsvSysAgentActions& aSysAgentActions );
void LoadSettingsL( CMsvScheduleSettings& aScheduleSettings, + CMsvOffPeakTimes& aOffPeakTimes, + CMsvSendErrorActions& aErrorActions, + MsvSysAgentActions& aSysAgentActions );
void SaveSettingsL(const CMsvScheduleSettings& aScheduleSettings, + const CMsvOffPeakTimes& aOffPeakTimes, + const CMsvSendErrorActions& aErrorActions, + const CMsvSysAgentActions& aSysAgentActions ) const; +

Procedure

Create an SMS account +using the CSmsAccount::NewL() function.
Create an object of CSmsSettings (SMS +service) and set it with appropriate settings as per your requirement.
For +instructions on creating an SMS account and using the settings APIs, see SMS Tutorial.
Create an instance of CMsvScheduleSettings to +specify general settings for sending a message.
Load the schedule send +settings using the LoadSettingsL() function.
Save the settings using +the SaveSettingsL() function.

+// 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
Create an SMS message +and set SetSendingState() and SetScheduled().

+ //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);
Send the message at +a specified time.

To set a message to be sent at a specified time:
1. Update the time to send, +using TMsvEntry::iDate, with the scheduled time.
2. Create a selection of +messages to be sent using CMsvEntrySelection.
  
  Note: +Every message in the selection must have the same scheduled time.
3. Add the message to the +selection.
4. Call CSmsClientMtm::InvokeAsyncFunctionL() with +command ID ESmsMtmCommandScheduleCopy.
The following code snippet schedules a message to be sent in on day’s +time:

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 +

When the scheduled task occurs, not only will the selected messages +be sent but also any waiting SMS messages in the Outbox.
Messages successfully sent by the scheduled task are moved to the Sent +folder.

Messages can be removed from the scheduler using the asynchronous +function ID ESmsMtmCommandDeleteSchedule.

Resend +on errors or failed conditions

A message can be rescheduled at two +stages of sending:

If send conditions are +not met (as seen above): The behaviour when this occurs is configured as part +of the send actions.
If sending to any recipient +fails: The behaviour in this event is determined by a SEND_ERROR_ACTIONS resource +in the SMS Server MTM resource file (in the device ROM). The resource specifies +the actions that must be taken if errors occur.

Two additional factors can prevent rescheduling occurring:

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 CMsvSysAgentActions error +action.
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 CMsvScheduleSettings::SetPendingConditionsTimeout() function. +The default is 0 (no timeout). The CMsvScheduleSettings is +a separate stream in the SMS service entry store.