This section provides an overview of the Schedule Send MTM component.
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.
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, see Task Scheduler.
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.
Figure: 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.
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.
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.
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. |