|
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-AA978F65-C25B-59DC-82BC-6892228EA3F9" xml:lang="en"><title>Schedule |
|
13 Send Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Schedule Send MTM (Message Type Module) allows other MTMs to send messages |
|
15 at scheduled times. </p> |
|
16 <p>This tutorial describes how to schedule SMS sending. For instructions on |
|
17 sending SMS messages, see <xref href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita">SMS |
|
18 Tutorial</xref>. </p> |
|
19 <section><title>Required background</title> <p>Before you start, you must |
|
20 understand: </p> <ul> |
|
21 <li id="GUID-E818F9A1-74F9-56A2-ADE6-421E3CEFA625"><p><xref href="GUID-33C7EEEB-88B8-5587-916D-2C5D122F6010.dita">SMS |
|
22 MTM</xref> </p> </li> |
|
23 </ul> </section> |
|
24 <section><title>Introduction</title> <p>Scheduled Send MTM enables you to |
|
25 do the following tasks: </p> <ul> |
|
26 <li id="GUID-7BE42BD7-E4BC-586E-987F-2F7AD54EB1AC"><p>Schedule a message to |
|
27 be sent at a specific scheduled time. </p> </li> |
|
28 <li id="GUID-E05C56E1-5AB2-50E8-ADD1-F5FEFDA48A3A"><p>Check whether specified |
|
29 conditions are met before sending a message. </p> </li> |
|
30 <li id="GUID-18AE81ED-E795-55BD-9796-41AAFA43D021"><p>Resend a message if |
|
31 an error occurs while sending. </p> </li> |
|
32 </ul> <p>An SMS service can have configuration settings which control the |
|
33 scheduled sending of messages. These configuration settings are in four parts: </p> <ul> |
|
34 <li id="GUID-FE65B7D1-C834-5F38-B766-4CFAA79152AB"><p>General settings: <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> </p> </li> |
|
35 <li id="GUID-2E2F2C04-41F4-587D-A222-DFBDC5903AB0"><p>Off-peak times settings: <xref href="GUID-E58A2F58-AF45-3D97-ACA6-6548FE507C3D.dita"><apiname>CMsvOffPeakTimes</apiname></xref>, |
|
36 which contains <xref href="GUID-0FAB21AD-16D5-34F4-A8E4-6A75EA02566E.dita"><apiname>TMsvOffPeakTime</apiname></xref> objects </p> </li> |
|
37 <li id="GUID-EC741167-6EBD-5E1C-956B-CE1AE755CB67"><p>Send error actions settings: <xref href="GUID-BF841328-372B-3F68-8BC9-5CB8639650D0.dita"><apiname>CMsvSendErrorActions</apiname></xref>, |
|
38 which contains <xref href="GUID-4F039FEB-4821-3871-A5CF-0D453BF91EAD.dita"><apiname>TMsvSendErrorAction</apiname></xref> objects </p> </li> |
|
39 <li id="GUID-1E957A78-1369-5DAE-9AAD-8A833AC1AA1A"><p>System agent actions |
|
40 settings: <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref>, which contains <xref href="GUID-322332B3-5259-3D51-A9AF-CFA2CD5617B6.dita"><apiname>TMsvSysAgentConditionAction</apiname></xref> objects </p> </li> |
|
41 </ul> <p>The above settings can be initialised and edited by a client application |
|
42 using the following member functions of <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita"><apiname>CSmsAccount</apiname></xref>: </p> <ul> |
|
43 <li id="GUID-C724F70C-3299-57DB-9152-5059F398FDC1"><codeblock id="GUID-90932F48-82BA-5D61-A011-3EC155753146" xml:space="preserve">void InitialiseDefaultSettingsL( CMsvScheduleSettings& aScheduleSettings, |
|
44 CMsvOffPeakTimes& aOffPeakTimes, |
|
45 CMsvSendErrorActions& aErrorActions, |
|
46 CMsvSysAgentActions& aSysAgentActions ); </codeblock> </li> |
|
47 <li id="GUID-B220B17C-DBEF-56FF-8AC5-A9B760E27660"><codeblock id="GUID-59F2D2ED-0BF3-5802-92FF-F1D93B7CD3F0" xml:space="preserve">void LoadSettingsL( CMsvScheduleSettings& aScheduleSettings, |
|
48 CMsvOffPeakTimes& aOffPeakTimes, |
|
49 CMsvSendErrorActions& aErrorActions, |
|
50 MsvSysAgentActions& aSysAgentActions );</codeblock> </li> |
|
51 <li id="GUID-9993E309-541D-58A9-9556-E767848533D3"><codeblock id="GUID-6E50378E-21E6-509B-ABB0-5F1D21F132FA" xml:space="preserve">void SaveSettingsL(const CMsvScheduleSettings& aScheduleSettings, |
|
52 const CMsvOffPeakTimes& aOffPeakTimes, |
|
53 const CMsvSendErrorActions& aErrorActions, |
|
54 const CMsvSysAgentActions& aSysAgentActions ) const; |
|
55 </codeblock> </li> |
|
56 </ul> </section> |
|
57 <section><title>Procedure</title> <ol id="GUID-8AE541F3-1B0A-5D1D-AA3E-9D56B9513B38"> |
|
58 <li id="GUID-73A15840-8DC6-5EEE-BCCD-36AE86BC30EC"><p>Create an SMS account |
|
59 using the <xref href="GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF.dita#GUID-40DD66D7-D08E-3A04-9583-1C5E60E352FF/GUID-91341F9C-C5DF-35A4-9E09-8EC18A96938A"><apiname>CSmsAccount::NewL()</apiname></xref> function. </p> </li> |
|
60 <li id="GUID-9E5F5C1B-D4A3-5A5F-A351-FBDC34CC8F9C"><p>Create an object of <xref href="GUID-A9FE5C23-4F39-345E-873B-682D9807BAA0.dita"><apiname>CSmsSettings</apiname></xref> (SMS |
|
61 service) and set it with appropriate settings as per your requirement. </p> <note> For |
|
62 instructions on creating an SMS account and using the settings APIs, see <xref href="GUID-A2408186-1927-45F4-8972-C9273E5135CF.dita">SMS Tutorial</xref>. </note> </li> |
|
63 <li id="GUID-5125AF39-9039-5257-9260-579ADAEF7AFC"><p>Create an instance of <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> to |
|
64 specify general settings for sending a message. </p> </li> |
|
65 <li id="GUID-01448B12-C1A7-5E5E-8991-2095363AF338"><p>Load the schedule send |
|
66 settings using the <xref href="GUID-31D274E3-CCD9-3948-912A-C3328D507A9A.dita"><apiname>LoadSettingsL()</apiname></xref> function. </p> </li> |
|
67 <li id="GUID-BF412FB6-DF4A-5EE9-9BED-5C95FFFD84F8"><p>Save the settings using |
|
68 the <xref href="GUID-BBACEDE8-3EB6-3486-996B-1188AF15752C.dita"><apiname>SaveSettingsL()</apiname></xref> function. </p> <p><codeblock id="GUID-9F54ADF1-4015-5D7D-BEA1-F0DDFEB2360D" xml:space="preserve"> |
|
69 // See SMS tutorial for detailed instructions on the initial set up of SMS, such as message server session, |
|
70 // MTM, SMS account and SMS message |
|
71 |
|
72 // Create objects for schedule send settings |
|
73 |
|
74 CMsvScheduleSettings* scheduleSettings = CMsvScheduleSettings::NewLC(); |
|
75 TTimeIntervalSeconds interval(5); |
|
76 scheduleSettings->SetShortInterval(interval); |
|
77 |
|
78 // Load the schedule send settings |
|
79 smsAccount->LoadSettingsL(*scheduleSettings, *offPeakTimes); |
|
80 |
|
81 // save the settings |
|
82 CSmsAccount *smsAccount = CSmsAccount::NewLC(); |
|
83 smsAccount->SaveSettingsL( *scheduleSettings, *offPeakTimes); |
|
84 CleanupStack::PopAndDestroy(); // scheduleSettings, smsAccount</codeblock> </p> </li> |
|
85 <li id="GUID-47E51360-87FF-5742-A08F-9653B34BF2B8"><p>Create an SMS message |
|
86 and set <xref href="GUID-7D31C4C6-2752-39E5-A789-73AD516F5CBD.dita"><apiname>SetSendingState()</apiname></xref> and <xref href="GUID-895BE1CB-1D52-33A0-B280-485D06088DB2.dita"><apiname>SetScheduled()</apiname></xref>. </p> <p><codeblock id="GUID-D8D7734B-2BA2-5D5E-8A55-11E0F2A75C58" xml:space="preserve"> |
|
87 //Create an SMS message (set up index entry) |
|
88 TMsvEntry newEntry; |
|
89 newEntry.iType = KUidMsvMessageEntry; |
|
90 newEntry.iServiceId = KMsvLocalServiceIndexEntryId; |
|
91 newEntry.iMtm = KUidMsgTypeSMS; |
|
92 newEntry.SetVisible(EFalse); |
|
93 newEntry.SetInPreparation(ETrue); |
|
94 newEntry.SetSendingState(KMsvSendStateWaiting); |
|
95 newEntry.SetScheduled(ETrue);</codeblock> </p> </li> |
|
96 <li id="GUID-3594C62C-099C-53AE-A9FE-E6F57D7DD3E6"><p>Send the message at |
|
97 a specified time. </p> <p>To set a message to be sent at a specified time: </p> <ol id="GUID-B030C1F9-6779-5244-9FDC-611D0F4A8A5E"> |
|
98 <li id="GUID-4B74937C-8A41-5024-9508-2806245FA2FC"><p>Update the time to send, |
|
99 using <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita#GUID-5A23B804-2C06-3407-9D48-1BFB212D699F/GUID-F60F7920-792C-3E53-870F-FC5BFFF84C73"><apiname>TMsvEntry::iDate</apiname></xref>, with the scheduled time. </p> </li> |
|
100 <li id="GUID-132F5600-986B-5AE8-A1E1-8F99D646FEEB"><p>Create a selection of |
|
101 messages to be sent using <xref href="GUID-6BC8851B-D913-3CE5-B343-5163661E8AD5.dita"><apiname>CMsvEntrySelection</apiname></xref>. </p> <p> Note: |
|
102 Every message in the selection must have the same scheduled time. </p> </li> |
|
103 <li id="GUID-E725D40B-2806-5D5F-8A5C-49E9AF9281DC"><p>Add the message to the |
|
104 selection. </p> </li> |
|
105 <li id="GUID-A9AA2EA7-6F52-53CF-8482-1C7E02C88118"><p>Call <xref href="GUID-C499ABDB-BA30-3D97-A850-D5790FE49634.dita#GUID-C499ABDB-BA30-3D97-A850-D5790FE49634/GUID-986D06BF-8427-338A-8EFC-9369E88D62C3"><apiname>CSmsClientMtm::InvokeAsyncFunctionL()</apiname></xref> with |
|
106 command ID <codeph>ESmsMtmCommandScheduleCopy</codeph>. </p> </li> |
|
107 </ol> <p>The following code snippet schedules a message to be sent in on day’s |
|
108 time: </p> <p><codeblock id="GUID-CD68D5F5-3BC3-5B51-A1E4-202233C81ECF" xml:space="preserve">CMsvEntrySelection* smsEntries = new (ELeave) CMsvEntrySelection; |
|
109 CleanupStack::PushL(smsEntries); |
|
110 TMsvId entryId; |
|
111 entryId=newEntry->Id(); |
|
112 |
|
113 // Set the scheduled time for tomorrow |
|
114 TTime t; |
|
115 t.HomeTime(); |
|
116 t += TTimeIntervalDays(1); |
|
117 newEntry.iDate=t;// update the time to send in the message (TMvsEntry) itself. |
|
118 |
|
119 // Create a selection of messages to send |
|
120 CMsvEntrySelection* smsEntries = new (ELeave) CMsvEntrySelection; |
|
121 CleanupStack::PushL(smsEntries); |
|
122 |
|
123 // Add the newly scheduled message to the selection |
|
124 smsEntries->AppendL( newEntry->Id() ); |
|
125 TBuf8<1> p; |
|
126 CMsvOperation* op = iMtm->InvokeAsyncFunctionL(ESmsMtmCommandScheduleCopy, |
|
127 *smsEntries, p, iStatus); |
|
128 CleanupStack::PopAndDestroy(); //smsEntries |
|
129 </codeblock> </p> </li> |
|
130 </ol> <note> <ul> |
|
131 <li><p>When the scheduled task occurs, not only will the selected messages |
|
132 be sent but also any waiting SMS messages in the Outbox.</p></li> |
|
133 <li><p>Messages successfully sent by the scheduled task are moved to the Sent |
|
134 folder.</p></li> |
|
135 </ul></note><p>Messages can be removed from the scheduler using the asynchronous |
|
136 function ID <codeph>ESmsMtmCommandDeleteSchedule</codeph>. </p><p><b>Resend |
|
137 on errors or failed conditions</b></p><p>A message can be rescheduled at two |
|
138 stages of sending: </p><ul> |
|
139 <li id="GUID-B3FC8C98-D165-5E7A-B2F5-9D42CDE2807E"><p>If send conditions are |
|
140 not met (as seen above): The behaviour when this occurs is configured as part |
|
141 of the send actions. </p> </li> |
|
142 <li id="GUID-4154A12E-A6D8-5C90-BD0C-AF305BE63BA6"><p>If sending to any recipient |
|
143 fails: The behaviour in this event is determined by a <xref href="GUID-86A889FA-CF7F-3B67-9D9E-349E3E0155CC.dita"><apiname>SEND_ERROR_ACTIONS</apiname></xref> resource |
|
144 in the SMS Server MTM resource file (in the device ROM). The resource specifies |
|
145 the actions that must be taken if errors occur. </p> </li> |
|
146 </ul><p>Two additional factors can prevent rescheduling occurring: </p><ul> |
|
147 <li id="GUID-6D141526-EB60-53B3-A734-1477CB4372D7"><p>In order to avoid an |
|
148 infinite loop of attempting to send a message, which may result in running |
|
149 the device battery down, a rescheduled message can be limited to a maximum |
|
150 number of re-tries. If the maximum number of re-tries is reached, then the |
|
151 message marked as failed and no further retries are attempted. The maximum |
|
152 number of re-tries is defined in the <xref href="GUID-95828565-7389-381C-BD7E-B7F7B98A2487.dita"><apiname>CMsvSysAgentActions</apiname></xref> error |
|
153 action. </p> </li> |
|
154 <li id="GUID-9483768D-B2CA-5616-B789-B6519F5E6826"><p>A timeout can be specified |
|
155 for waiting for sending conditions to occur. If the timeout occurs before |
|
156 the conditions are met the pending SMS messages are marked as failed. The |
|
157 timeout is configurable through the <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita#GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA/GUID-DF0D64F1-5408-335C-8FA8-FE5F874B97E4"><apiname>CMsvScheduleSettings::SetPendingConditionsTimeout()</apiname></xref> function. |
|
158 The default is 0 (no timeout). The <xref href="GUID-3A9254B7-77C2-300A-9128-6A7BD45F8CBA.dita"><apiname>CMsvScheduleSettings</apiname></xref> is |
|
159 a separate stream in the SMS service entry store. </p> </li> |
|
160 </ul></section> |
|
161 <section><title>See also</title> <p><xref href="GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A.dita">Schedule |
|
162 Send MTM Overview</xref> </p> </section> |
|
163 </conbody></concept> |