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.

Required background

Before you start, you must -understand:

SMS -MTM

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.