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:

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:

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

  1. Create an SMS account using the CSmsAccount::NewL() function.

  2. Create an object of CSmsSettings (SMS service) and set it with appropriate settings as per your requirement.

    Note: For instructions on creating an SMS account and using the settings APIs, see SMS Tutorial.

  3. Create an instance of CMsvScheduleSettings to specify general settings for sending a message.

  4. Load the schedule send settings using the LoadSettingsL() function.

  5. 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
  6. 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);
  7. 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
    

Note:

  • 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.