1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A" xml:lang="en"><title>Schedule

    13 Send MTM Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>This section provides an overview of the Schedule Send MTM component. </p>

    15 <section><title>Purpose</title> <p>The Schedule Send MTM allows Message Type

    16 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

    17 functionality to allow scheduled sending of SMS messages. </p> </section>

    18 <section><title>Architecture</title> <p>The Schedule Send functionality is

    19 delivered by four components: </p> <ul>

    20 <li id="GUID-9F8C6A75-11C5-58F8-8C94-ABFEFB5551A7"><p> <b>Server MTM base

    21 class</b>  </p> <p>The base class provides support to Server MTMs that wish

    22 to support scheduled operations. </p> </li>

    23 <li id="GUID-B0BC4BCD-600A-5619-AA0A-721DFA6F6355"><p> <b>Data structures</b>  </p> <p>Classes

    24 used to represent the data associated with a scheduled operation. </p> </li>

    25 <li id="GUID-D096C050-6250-5C6B-8046-C6BEC1BBB4DA"><p> <b>Schedule Send Executable</b>  </p> <p>The

    26 Schedule Send Executable is run by the task scheduler at the scheduled time. </p> </li>

    27 <li id="GUID-FEC0314A-5D66-570B-BCD2-A995FA9B52EC"><p> <b>Task Scheduler</b>  </p> <p>The

    28 component is part of the Generic OS Services. </p> </li>

    29 </ul> <p>Clients request the Server MTM schedule operations; this is passed

    30 to the Server MTM through the Message Server. The Server MTM packages the

    31 operation ID, a selection of message IDs, how often to poll for progress and

    32 an MTM specific buffer. It then passes this package of data to the task scheduler

    33 requesting that it launches the Schedule Send executable at the correct time

    34 with the packaged information. When the task scheduler launches the Schedule

    35 Send executable, it unpacks the schedule information and uses the messaging

    36 client API to request the Server MTM to perform an operation. </p> <fig id="GUID-F3664A22-1E9F-586B-84B1-CDA7987C3894">

    37 <title>              Schedule Send architecture            </title>

    38 <image href="GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e280334_href.png" placement="inline"/>

    39 </fig> <p>The executable to run by the Task Scheduler is specified in the

    40 schedule send settings. This allows different executables for different message

    41 types, as a set of schedule send settings are defined for each message type

    42 that uses the schedule send support. The executable is normally the schedule-send

    43 exe (<filepath>schsendexe.exe</filepath>). </p> <p>Each task contains some

    44 repeat and priority information and a payload of data. In the case of schedules

    45 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

    46 the scheduled message and ID of the command to be applied to that message. </p> </section>

    47 <section><title>Description</title> <p>The Schedule Send component is an extension

    48 to the Messaging Framework that provides the messaging client with functionality

    49 to schedule messages. It provides the following scheduling functionality: </p> <ul>

    50 <li id="GUID-D0FE4E53-6A5E-537C-8137-62FCBDA76C25"><p>Schedule a selection

    51 of messages </p> </li>

    52 <li id="GUID-310D7333-C3A4-544F-82F9-EBED51DEC322"><p>Reschedule a selection

    53 of messages </p> </li>

    54 <li id="GUID-E55C0577-3E52-57F8-9DE0-A74DD6504699"><p>Check the schedule information

    55 for a selection of messages </p> </li>

    56 <li id="GUID-A7553674-42EC-5437-A362-5994776B2D79"><p>Delete the schedule(s)

    57 for a selection of messages </p> </li>

    58 </ul> <p>It also provides status information, such as whether a message is

    59 currently scheduled, or failed. </p> <p>There are two types of schedules:

    60 conditions-schedules and time-schedules. Both are stored in the file system

    61 and persist across a reboot of a device. A schedule contains several pieces

    62 of information, such as the schedule trigger (for example, the scheduled time),

    63 the executable to run when the trigger occurs, and a list of tasks. </p> <p>Schedule

    64 Send supports a retry mechanism if the operation fails. The Server MTM has

    65 a resource file containing a mapping from the error codes the operation can

    66 fail with and actions to be performed. For example, the SMS resource file

    67 has a mapping such that if the operation fails with an error code indicating

    68 a bad phone number, the SMS is set to failed and left in the outbox. Whereas,

    69 if it fails with an error code indicating temporary network failure, the send

    70 operation is scheduled to be resent later with a maximum of three retries. </p> </section>

    71 <section><title>API summary</title> <p>The following are the main classes

    72 of the Schedule Send component: </p> <ul>

    73 <li id="GUID-FC3E3A59-29FD-5AD9-A4FE-3712BBE84F4F"><p>The <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref> is

    74 the main API that provides the Schedule Send support. This API provides the

    75 following scheduling functionality: </p> <ul>

    76 <li id="GUID-21BA2FDE-617B-521C-82E6-B6493677234D"><p>Schedule a selection

    77 of messages </p> </li>

    78 <li id="GUID-7A3D4A53-713C-50F1-9BCE-23C93795240B"><p>Reschedule a selection

    79 of messages </p> </li>

    80 <li id="GUID-81E94316-E1BE-5710-9573-5C9DD332E9C4"><p>Check the schedule information

    81 for a selection of messages </p> </li>

    82 <li id="GUID-5DAA73B7-5171-5F17-9F09-FBA1006BC69C"><p>Delete the schedules

    83 for a selection of messages </p> </li>

    84 </ul> <p>Scheduling is performed by the task scheduler. The <xref href="GUID-35CAC635-C0CE-328F-B10C-7FEB4503E8DB.dita"><apiname>CMsvScheduleSend</apiname></xref> class

    85 uses the task scheduler <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita"><apiname>RScheduler</apiname></xref> API to create persistent

    86 schedules and add tasks to that schedule. Each task contains some repeat and

    87 priority information, and a payload of data. In the case of schedules created

    88 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

    89 the scheduled message and the ID of the command to be applied to that message. </p> </li>

    90 <li id="GUID-88A357B8-1F54-5BB4-8996-749E08776880"><p>The <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref> class

    91 is used to specify what (system agent) conditions need to be checked before

    92 sending a message. </p> </li>

    93 <li id="GUID-6B42C963-B955-5928-8CC9-D27D3D4B49C5"><p>The <xref href="GUID-BF841328-372B-3F68-8BC9-5CB8639650D0.dita"><apiname>CMsvSendErrorActions</apiname></xref> class

    94 has a set of actions associated with error codes. It also provides a method

    95 to populate itself from a resource file, <xref href="GUID-30427874-08F3-32E1-A512-44091C4ABD5C.dita"><apiname>RestoreFromResourceL</apiname></xref>. </p> <p>This

    96 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,

    97 where the error actions are populated from the resource file for a message

    98 type. </p> </li>

    99 <li id="GUID-3C17AEBA-7F45-51A4-A2EB-C4E0EC64869E"><p>The <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> class

   100 encapsulates settings for the Schedule Send. This contains information, such

   101 as, the length of <b>short</b> and <b>long</b> time intervals that are used

   102 to calculate the next schedule time for a message being rescheduled. </p> </li>

   103 </ul> </section>

   104 <section><title>Typical uses</title> <table id="GUID-B9D02EE0-1A69-5540-AE43-23A2ADA52F98">

   105 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

   106 <thead>

   107 <row>

   108 <entry>Main task</entry>

   109 <entry>Sub-tasks</entry>

   110 <entry>Description</entry>

   111 </row>

   112 </thead>

   113 <tbody>

   114 <row>

   115 <entry><p>Scheduling a message </p> </entry>

   116 <entry><p> </p> </entry>

   117 <entry><p>Schedules a selection of messages. The messages must be of the same

   118 type. They must also be scheduled for the same date and if applicable, for

   119 the same off-peak time. </p> <p>The first step of scheduling a message is

   120 to set the different parameters that allows determining the exact time the

   121 message is sent and what to do if the message cannot be sent. The following

   122 settings are per message and two parameters must be set for each message. </p> </entry>

   123 </row>

   124 <row>

   125 <entry><p> </p> </entry>

   126 <entry><p>Set the date </p> </entry>

   127 <entry><p>Client applications can set the schedule date for a message. </p> </entry>

   128 </row>

   129 <row>

   130 <entry><p> </p> </entry>

   131 <entry><p>Select off-peak sending </p> </entry>

   132 <entry><p>Client applications can select to send messages during off-peak

   133 periods. </p> </entry>

   134 </row>

   135 <row>

   136 <entry><p>Delete the schedule for messages </p> </entry>

   137 <entry><p> </p> </entry>

   138 <entry><p>Client applications can delete a schedule for a specified message

   139 from the task scheduler. The messages themselves are not deleted. </p> </entry>

   140 </row>

   141 <row>

   142 <entry><p>Re-schedule messages </p> </entry>

   143 <entry><p> </p> </entry>

   144 <entry><p>Client applications can determine when messages should be rescheduled

   145 on the task scheduler. </p> </entry>

   146 </row>

   147 <row>

   148 <entry><p>Send scheduled messages </p> </entry>

   149 <entry><p> </p> </entry>

   150 <entry><p>Client applications can send messages immediately that are previously

   151 scheduled, that is, override the scheduling. </p> </entry>

   152 </row>

   153 <row>

   154 <entry><p>Check the schedule of messages </p> </entry>

   155 <entry><p> </p> </entry>

   156 <entry><p>Client applications can verify that the schedule information stored

   157 in specified messages is the same as the one actually in use. </p> </entry>

   158 </row>

   159 <row>

   160 <entry><p>Configuring a Schedule Send message </p> </entry>

   161 <entry/>

   162 <entry><p>Client applications can configure the build-time configuration parameters,

   163 which are time-related parameters, off-peak period definitions and error actions. </p> </entry>

   164 </row>

   165 <row>

   166 <entry/>

   167 <entry><p>Validity period </p> </entry>

   168 <entry><p>The time period that the messages are valid (the message is not

   169 sent after the validity period has expired). This is ignored if a message

   170 has to be sent off-peak. </p> </entry>

   171 </row>

   172 <row>

   173 <entry/>

   174 <entry><p>Next attempt intervals </p> </entry>

   175 <entry><p>The messaging client uses this setting to define the time to wait

   176 before attempting to resend a message. </p> <p>After a failed attempt, a message

   177 can be sent immediately or later. The short interval and long interval define

   178 the delays before a new attempt. </p> </entry>

   179 </row>

   180 <row>

   181 <entry/>

   182 <entry><p>Latency </p> </entry>

   183 <entry><p>The minimum amount of time between now and when the message is sent. </p> <p>A

   184 message scheduled in the past will actually be scheduled to be sent Latency

   185 seconds after the current time. </p> </entry>

   186 </row>

   187 <row>

   188 <entry/>

   189 <entry><p>Start of off-peak period </p> </entry>

   190 <entry><p>The day of the week, hour of the day and minute of the hour when

   191 the off-peak period starts. </p> </entry>

   192 </row>

   193 <row>

   194 <entry/>

   195 <entry><p>Duration of off-peak period </p> </entry>

   196 <entry><p>The length (in minutes) of the off-peak period time. Must be less

   197 than 24 hours. </p> </entry>

   198 </row>

   199 <row>

   200 <entry/>

   201 <entry><p>Add an error action </p> </entry>

   202 <entry><p>Client applications can add an error-action to the configuration

   203 of the subsystem (for a type of message). That is, the error-action is configured

   204 for the number of retries or type of retry spacing to a particular error. </p> </entry>

   205 </row>

   206 <row>

   207 <entry/>

   208 <entry><p>Remove an error-action </p> </entry>

   209 <entry><p>Client applications can remove an error-action from the list sustained

   210 by the Messaging Middleware module. </p> </entry>

   211 </row>

   212 <row>

   213 <entry/>

   214 <entry><p>Set a list of error-actions </p> </entry>

   215 <entry><p> </p> </entry>

   216 </row>

   217 <row>

   218 <entry/>

   219 <entry><p>Load the error-actions from a resource file </p> </entry>

   220 <entry><p>Client applications can restore the list of error-actions from a

   221 resource file. </p> </entry>

   222 </row>

   223 </tbody>

   224 </tgroup>

   225 </table> </section>

   226 </conbody><related-links>

   227 <link href="GUID-8B843382-D27A-5E36-8F60-304903F3AA41.dita"><linktext>Message Type

   228 Module</linktext></link>

   229 </related-links></concept>