Collapse all Symbian^3 Product Developer Library

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.

Figure 1. 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.

Parent topic: Schedule Send MTM

Related concepts

Message Type Module