Schedule +Send MTM Overview

This section provides an overview of the Schedule Send MTM component.

Purpose

The Schedule Send MTM allows Message Type +Modules (MTM) to send messages at scheduled times. For example, the SMS MTM uses this +functionality to allow scheduled sending of SMS messages.

Architecture

The Schedule Send functionality is +delivered by four components:

Server MTM base +class

The base class provides support to Server MTMs that wish +to support scheduled operations.
Data structures

Classes +used to represent the data associated with a scheduled operation.
Schedule Send Executable

The +Schedule Send Executable is run by the task scheduler at the scheduled time.
Task Scheduler

The +component is part of the Generic OS Services.

Clients request the Server MTM schedule operations; this is passed +to the Server MTM through the Message Server. The Server MTM packages the +operation ID, a selection of message IDs, how often to poll for progress and +an MTM specific buffer. It then passes this package of data to the task scheduler +requesting that it launches the Schedule Send executable at the correct time +with the packaged information. When the task scheduler launches the Schedule +Send executable, it unpacks the schedule information and uses the messaging +client API to request the Server MTM to perform an operation.

+ Schedule Send architecture + +

The executable to run by the Task Scheduler is specified in the +schedule send settings. This allows different executables for different message +types, as a set of schedule send settings are defined for each message type +that uses the schedule send support. The executable is normally the schedule-send +exe (schsendexe.exe).

Each task contains some +repeat and priority information and a payload of data. In the case of schedules +created by CMsvScheduleSend, and the payload contains the TMsvId of +the scheduled message and ID of the command to be applied to that message.

Description

The Schedule Send component is an extension +to the Messaging Framework that provides the messaging client with functionality +to schedule messages. It provides the following scheduling functionality:

Schedule a selection +of messages
Reschedule a selection +of messages
Check the schedule information +for a selection of messages
Delete the schedule(s) +for a selection of messages

It also provides status information, such as whether a message is +currently scheduled, or failed.

There are two types of schedules: +conditions-schedules and time-schedules. Both are stored in the file system +and persist across a reboot of a device. A schedule contains several pieces +of information, such as the schedule trigger (for example, the scheduled time), +the executable to run when the trigger occurs, and a list of tasks.

Schedule +Send supports a retry mechanism if the operation fails. The Server MTM has +a resource file containing a mapping from the error codes the operation can +fail with and actions to be performed. For example, the SMS resource file +has a mapping such that if the operation fails with an error code indicating +a bad phone number, the SMS is set to failed and left in the outbox. Whereas, +if it fails with an error code indicating temporary network failure, the send +operation is scheduled to be resent later with a maximum of three retries.

API summary

The following are the main classes +of the Schedule Send component:

The CMsvScheduleSend is +the main API that provides the Schedule Send support. This API provides the +following scheduling functionality:
- Schedule a selection +of messages
- Reschedule a selection +of messages
- Check the schedule information +for a selection of messages
- Delete the schedules +for a selection of messages
Scheduling is performed by the task scheduler. The CMsvScheduleSend class +uses the task scheduler RScheduler API to create persistent +schedules and add tasks to that schedule. Each task contains some repeat and +priority information, and a payload of data. In the case of schedules created +by CMsvScheduleSend, the payload contains the TMsvId of +the scheduled message and the ID of the command to be applied to that message.
The CMsvSysAgentActions class +is used to specify what (system agent) conditions need to be checked before +sending a message.
The CMsvSendErrorActions class +has a set of actions associated with error codes. It also provides a method +to populate itself from a resource file, RestoreFromResourceL.

This +is used in the CScheduleBaseServerMtm::RestoreSettings method, +where the error actions are populated from the resource file for a message +type.
The CMsvScheduleSettings class +encapsulates settings for the Schedule Send. This contains information, such +as, the length of short and long time intervals that are used +to calculate the next schedule time for a message being rescheduled.

Typical uses + + + +Main task +Sub-tasks +Description + + + + +

Scheduling a message

Schedules a selection of messages. The messages must be of the same +type. They must also be scheduled for the same date and if applicable, for +the same off-peak time.

The first step of scheduling a message is +to set the different parameters that allows determining the exact time the +message is sent and what to do if the message cannot be sent. The following +settings are per message and two parameters must be set for each message.

+ + +

Set the date

Client applications can set the schedule date for a message.

+ + +

Select off-peak sending

Client applications can select to send messages during off-peak +periods.

+ + +

Delete the schedule for messages

Client applications can delete a schedule for a specified message +from the task scheduler. The messages themselves are not deleted.

+ + +

Re-schedule messages

Client applications can determine when messages should be rescheduled +on the task scheduler.

+ + +

Send scheduled messages

Client applications can send messages immediately that are previously +scheduled, that is, override the scheduling.

+ + +

Check the schedule of messages

Client applications can verify that the schedule information stored +in specified messages is the same as the one actually in use.

+ + +

Configuring a Schedule Send message

+ +

Client applications can configure the build-time configuration parameters, +which are time-related parameters, off-peak period definitions and error actions.

+ + + +

Validity period

The time period that the messages are valid (the message is not +sent after the validity period has expired). This is ignored if a message +has to be sent off-peak.

+ + + +

Next attempt intervals

The messaging client uses this setting to define the time to wait +before attempting to resend a message.

After a failed attempt, a message +can be sent immediately or later. The short interval and long interval define +the delays before a new attempt.

+ + + +

Latency

The minimum amount of time between now and when the message is sent.

A +message scheduled in the past will actually be scheduled to be sent Latency +seconds after the current time.

+ + + +

Start of off-peak period

The day of the week, hour of the day and minute of the hour when +the off-peak period starts.

+ + + +

Duration of off-peak period

The length (in minutes) of the off-peak period time. Must be less +than 24 hours.

+ + + +

Add an error action

Client applications can add an error-action to the configuration +of the subsystem (for a type of message). That is, the error-action is configured +for the number of retries or type of retry spacing to a particular error.

+ + + +

Remove an error-action

Client applications can remove an error-action from the list sustained +by the Messaging Middleware module.

+ + + +

Set a list of error-actions

+ + + +

Load the error-actions from a resource file

Client applications can restore the list of error-actions from a +resource file.

+ + + +