<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A" xml:lang="en"><title>Schedule
Send MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This section provides an overview of the Schedule Send MTM component. </p>
<section><title>Purpose</title> <p>The Schedule Send MTM allows Message Type
Modules (MTM) to send messages at scheduled times. For example, the <xref href="GUID-33C7EEEB-88B8-5587-916D-2C5D122F6010.dita">SMS MTM</xref> uses this
functionality to allow scheduled sending of SMS messages. </p> </section>
<section><title>Architecture</title> <p>The Schedule Send functionality is
delivered by four components: </p> <ul>
<li id="GUID-9F8C6A75-11C5-58F8-8C94-ABFEFB5551A7"><p> <b>Server MTM base
class</b>  </p> <p>The base class provides support to Server MTMs that wish
to support scheduled operations. </p> </li>
<li id="GUID-B0BC4BCD-600A-5619-AA0A-721DFA6F6355"><p> <b>Data structures</b>  </p> <p>Classes
used to represent the data associated with a scheduled operation. </p> </li>
<li id="GUID-D096C050-6250-5C6B-8046-C6BEC1BBB4DA"><p> <b>Schedule Send Executable</b>  </p> <p>The
Schedule Send Executable is run by the task scheduler at the scheduled time. </p> </li>
<li id="GUID-FEC0314A-5D66-570B-BCD2-A995FA9B52EC"><p> <b>Task Scheduler</b>  </p> <p>The
component is part of the Generic OS Services. </p> </li>
</ul> <p>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. </p> <fig id="GUID-F3664A22-1E9F-586B-84B1-CDA7987C3894">
<title>              Schedule Send architecture            </title>
<image href="GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e276648_href.png" placement="inline"/>
</fig> <p>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 (<filepath>schsendexe.exe</filepath>). </p> <p>Each task contains some
repeat and priority information and a payload of data. In the case of schedules
created by <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref>, and the payload contains the <xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> of
the scheduled message and ID of the command to be applied to that message. </p> </section>
<section><title>Description</title> <p>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: </p> <ul>
<li id="GUID-D0FE4E53-6A5E-537C-8137-62FCBDA76C25"><p>Schedule a selection
of messages </p> </li>
<li id="GUID-310D7333-C3A4-544F-82F9-EBED51DEC322"><p>Reschedule a selection
of messages </p> </li>
<li id="GUID-E55C0577-3E52-57F8-9DE0-A74DD6504699"><p>Check the schedule information
for a selection of messages </p> </li>
<li id="GUID-A7553674-42EC-5437-A362-5994776B2D79"><p>Delete the schedule(s)
for a selection of messages </p> </li>
</ul> <p>It also provides status information, such as whether a message is
currently scheduled, or failed. </p> <p>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. </p> <p>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. </p> </section>
<section><title>API summary</title> <p>The following are the main classes
of the Schedule Send component: </p> <ul>
<li id="GUID-FC3E3A59-29FD-5AD9-A4FE-3712BBE84F4F"><p>The <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref> is
the main API that provides the Schedule Send support. This API provides the
following scheduling functionality: </p> <ul>
<li id="GUID-21BA2FDE-617B-521C-82E6-B6493677234D"><p>Schedule a selection
of messages </p> </li>
<li id="GUID-7A3D4A53-713C-50F1-9BCE-23C93795240B"><p>Reschedule a selection
of messages </p> </li>
<li id="GUID-81E94316-E1BE-5710-9573-5C9DD332E9C4"><p>Check the schedule information
for a selection of messages </p> </li>
<li id="GUID-5DAA73B7-5171-5F17-9F09-FBA1006BC69C"><p>Delete the schedules
for a selection of messages </p> </li>
</ul> <p>Scheduling is performed by the task scheduler. The <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref> class
uses the task scheduler <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita"><apiname>RScheduler</apiname></xref> 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 <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref>, the payload contains the <xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> of
the scheduled message and the ID of the command to be applied to that message. </p> </li>
<li id="GUID-88A357B8-1F54-5BB4-8996-749E08776880"><p>The <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref> class
is used to specify what (system agent) conditions need to be checked before
sending a message. </p> </li>
<li id="GUID-6B42C963-B955-5928-8CC9-D27D3D4B49C5"><p>The <xref href="GUID-BF841328-372B-3F68-8BC9-5CB8639650D0.dita"><apiname>CMsvSendErrorActions</apiname></xref> class
has a set of actions associated with error codes. It also provides a method
to populate itself from a resource file, <xref href="GUID-30427874-08F3-32E1-A512-44091C4ABD5C.dita"><apiname>RestoreFromResourceL</apiname></xref>. </p> <p>This
is used in the <xref href="GUID-78B57F36-F131-3275-B23F-9F20446C5C2A.dita#GUID-78B57F36-F131-3275-B23F-9F20446C5C2A/GUID-6D031676-C9A7-36F3-B75A-363EA1571896"><apiname>CScheduleBaseServerMtm::RestoreSettings</apiname></xref> method,
where the error actions are populated from the resource file for a message
type. </p> </li>
<li id="GUID-3C17AEBA-7F45-51A4-A2EB-C4E0EC64869E"><p>The <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> class
encapsulates settings for the Schedule Send. This contains information, such
as, the length of <b>short</b> and <b>long</b> time intervals that are used
to calculate the next schedule time for a message being rescheduled. </p> </li>
</ul> </section>
<section><title>Typical uses</title> <table id="GUID-B9D02EE0-1A69-5540-AE43-23A2ADA52F98">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Main task</entry>
<entry>Sub-tasks</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>Scheduling a message </p> </entry>
<entry><p> </p> </entry>
<entry><p>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. </p> <p>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. </p> </entry>
</row>
<row>
<entry><p> </p> </entry>
<entry><p>Set the date </p> </entry>
<entry><p>Client applications can set the schedule date for a message. </p> </entry>
</row>
<row>
<entry><p> </p> </entry>
<entry><p>Select off-peak sending </p> </entry>
<entry><p>Client applications can select to send messages during off-peak
periods. </p> </entry>
</row>
<row>
<entry><p>Delete the schedule for messages </p> </entry>
<entry><p> </p> </entry>
<entry><p>Client applications can delete a schedule for a specified message
from the task scheduler. The messages themselves are not deleted. </p> </entry>
</row>
<row>
<entry><p>Re-schedule messages </p> </entry>
<entry><p> </p> </entry>
<entry><p>Client applications can determine when messages should be rescheduled
on the task scheduler. </p> </entry>
</row>
<row>
<entry><p>Send scheduled messages </p> </entry>
<entry><p> </p> </entry>
<entry><p>Client applications can send messages immediately that are previously
scheduled, that is, override the scheduling. </p> </entry>
</row>
<row>
<entry><p>Check the schedule of messages </p> </entry>
<entry><p> </p> </entry>
<entry><p>Client applications can verify that the schedule information stored
in specified messages is the same as the one actually in use. </p> </entry>
</row>
<row>
<entry><p>Configuring a Schedule Send message </p> </entry>
<entry/>
<entry><p>Client applications can configure the build-time configuration parameters,
which are time-related parameters, off-peak period definitions and error actions. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Validity period </p> </entry>
<entry><p>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. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Next attempt intervals </p> </entry>
<entry><p>The messaging client uses this setting to define the time to wait
before attempting to resend a message. </p> <p>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. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Latency </p> </entry>
<entry><p>The minimum amount of time between now and when the message is sent. </p> <p>A
message scheduled in the past will actually be scheduled to be sent Latency
seconds after the current time. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Start of off-peak period </p> </entry>
<entry><p>The day of the week, hour of the day and minute of the hour when
the off-peak period starts. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Duration of off-peak period </p> </entry>
<entry><p>The length (in minutes) of the off-peak period time. Must be less
than 24 hours. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Add an error action </p> </entry>
<entry><p>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. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Remove an error-action </p> </entry>
<entry><p>Client applications can remove an error-action from the list sustained
by the Messaging Middleware module. </p> </entry>
</row>
<row>
<entry/>
<entry><p>Set a list of error-actions </p> </entry>
<entry><p> </p> </entry>
</row>
<row>
<entry/>
<entry><p>Load the error-actions from a resource file </p> </entry>
<entry><p>Client applications can restore the list of error-actions from a
resource file. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
</conbody><related-links>
<link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type
Module</linktext></link>
</related-links></concept>