|
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 task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-74C1C345-823C-5CD5-8FC5-214A55734E94" xml:lang="en"><title>Developing |
|
13 Programs with Task Scheduling Capabilities</title><abstract><p>Symbian Developers and device creators can use the task scheduler |
|
14 APIs to develop programs with scheduling capabilities. Programs may need task |
|
15 scheduling capabilities to support scheduling options that may be required |
|
16 for a phone user, another program or a system server. </p><p>For example, |
|
17 a phone user can use the alarm option of a clock application to schedule an |
|
18 alarm to be triggered every day at 5:00 A.M. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
19 <steps id="GUID-17AC6716-B2C4-5C14-9764-109D31C3B9DA"> |
|
20 <step id="GUID-C6EB0627-BD29-50F5-8A80-2581284DC750"><cmd/> |
|
21 <info>Connect the client to the task scheduler server using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-C4EEE075-3B47-3964-AFCC-0CDF09DEDA0F"><apiname>RScheduler::Connect()</apiname></xref>. </info> |
|
22 <stepxmp><codeblock id="GUID-5D5D73EF-7642-5D91-91EA-09E562F93AE8" xml:space="preserve">RScheduler iScheduler; |
|
23 User::LeaveIfError(iScheduler.Connect());</codeblock> </stepxmp> |
|
24 </step> |
|
25 <step id="GUID-F442887C-9F99-50AF-89B3-7B9532E15A8C"><cmd/> |
|
26 <info>Register the client with the task scheduler server using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-C19048C5-DC9F-3B8A-B4AD-02C0D943B7AC"><apiname>RScheduler::Register()</apiname></xref> by |
|
27 passing the following parameters: </info> |
|
28 <substeps id="GUID-B8842174-43F3-5B5D-8906-7699B89A53C8"> |
|
29 <substep id="GUID-E95387B3-CFAA-5523-8105-1999FD5FD309"><cmd/> |
|
30 <info>Name and full path of the executable to be used to execute the scheduled |
|
31 task. For more information about creating this executable, see the <filepath>taskexecutor.cpp</filepath> topic |
|
32 in the<xref href="GUID-8B938FEF-4D70-4589-921C-C99667193E20.dita">TaskSchedulerExample: |
|
33 Using Task Scheduler for Creating and Executing Tasks</xref> section. </info> |
|
34 </substep> |
|
35 <substep id="GUID-A1655664-C67A-5DDD-BF3E-E8DDC98F1FB6"><cmd/> |
|
36 <info>Priority of the task to be executed, relative to other clients. If two |
|
37 clients have tasks to execute at the same time, the one with the higher priority |
|
38 is executed first. </info> |
|
39 </substep> |
|
40 </substeps> |
|
41 <info>The following code snippet illustrates how to register a client with |
|
42 the task scheduler server: </info> |
|
43 <stepxmp><codeblock id="GUID-FFF2F47A-10AC-543D-B090-77E6B01A0C62" xml:space="preserve">RScheduler iScheduler; |
|
44 TFileName fileName; |
|
45 ... |
|
46 |
|
47 //A priority value |
|
48 const TInt priority = 3; |
|
49 |
|
50 ... |
|
51 |
|
52 User::LeaveIfError(iScheduler.Register(filename, priority));</codeblock> </stepxmp> |
|
53 <info><note>Task scheduler supports only the execution of Symbian platform |
|
54 executables. The <codeph>aFileName</codeph> parameter can include a path but |
|
55 must not include a file extension. </note></info> |
|
56 <info>For example, a <codeph>fileName</codeph> can be <filepath>minimalTaskHandler</filepath>. |
|
57 Note that in the presence of platform security all EXEs are located in the <filepath>\sys\bin</filepath> folder |
|
58 and as a consequence of this, the path of an EXE (only the drive letter) is |
|
59 not needed. </info> |
|
60 </step> |
|
61 <step id="GUID-5D132AE0-6A8D-5A56-A52B-2CE8151CC757"><cmd/> |
|
62 <info>Create the support for different types of schedules that you want to |
|
63 provide using the following functions of <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita"><apiname>RScheduler</apiname></xref>: </info> |
|
64 <substeps id="GUID-4F006CFD-2A46-568F-8495-E5B61CBDE4BB"> |
|
65 <substep id="GUID-128E5806-8499-5F19-97ED-F9022046C128"><cmd/> |
|
66 <info> <xref href="GUID-5CF2FCCF-552B-3BDF-8024-32F895583C8A.dita"><apiname>IMPORT_C TInt CreatePersistentSchedule(TSchedulerItemRef& |
|
67 aRef, const CArrayFixFlat<TScheduleEntryInfo2>& aEntryList)</apiname></xref>:Creates |
|
68 a persistent time-based schedule without tasks. </info> |
|
69 <info>The following code snippet illustrates how to create a persistent time-based |
|
70 schedule scheduled to start on January 1st, 2010 at 08:00 A.M., runs every |
|
71 one hour and is valid for eight hours. </info> |
|
72 <stepxmp><codeblock id="GUID-E791116D-722C-5F25-BBE5-B4C0DEC5A29A" xml:space="preserve">... |
|
73 |
|
74 TSchedulerItemRef& aRef; |
|
75 |
|
76 //Array to hold the schedule entries |
|
77 CArrayFixFlat<TScheduleEntryInfo2>* cSchEntryInfoArray; |
|
78 cSchEntryInfoArray = new CArrayFixFlat<TScheduleEntryInfo2>(1); |
|
79 |
|
80 CleanupStack::PushL(cSchEntryInfoArray); |
|
81 |
|
82 // Create an hourly schedule |
|
83 TScheduleEntryInfo2 entry1; |
|
84 |
|
85 //Sets the date and time for the schedule as Jan 1st, 2010, 08:00 am |
|
86 TDateTime datetime2(2010, EJanuary, 1, 8, 0, 0, 0); |
|
87 TTsTime time2(datetime2, ETrue); |
|
88 |
|
89 //Set the first instance when the entry will cause the execution of tasks. |
|
90 entry1.SetStartTime(time2); |
|
91 |
|
92 // Set the interval between execution of tasks |
|
93 // Here the interval is 2 hours because the interval type is hourly. |
|
94 const TInt interval = 2; |
|
95 entry1.SetInterval(interval); |
|
96 |
|
97 // Set the type of interval used between due times for the scheduled entry |
|
98 entry1.SetIntervalType(TIntervalType(EHourly)); |
|
99 |
|
100 // Set the period for which the entry is valid. After 8 hours the |
|
101 // tasks associated with the entry will not be eligible for execution. |
|
102 const TInt eightHours = 480; // in minutes |
|
103 entry1.SetValidityPeriod(TTimeIntervalMinutes(eightHours)); |
|
104 |
|
105 cSchEntryInfoArray->AppendL(entry1); |
|
106 |
|
107 //create the time-based persistent schedule |
|
108 User::LeaveIfError(iScheduler.CreatePersistentSchedule(aRef, *cSchEntryInfoArray)); |
|
109 |
|
110 CleanupStack::PopAndDestroy(cSchEntryInfoArray); |
|
111 ...</codeblock> </stepxmp> |
|
112 </substep> |
|
113 <substep id="GUID-FFC11C40-D971-5122-B07C-32695C61EE64"><cmd/> |
|
114 <info> <xref href="GUID-5A30CCBC-8D18-359A-ABB1-E4256ADC7199.dita"><apiname>IMPORT_C TInt CreatePersistentSchedule(TSchedulerItemRef& |
|
115 aRef, const CArrayFixFlat<TTaskSchedulerCondition>& aConditions, const |
|
116 TTsTime& aDefaultRunTime)</apiname></xref>: Creates a persistent condition-based |
|
117 schedule without tasks. </info> |
|
118 <info>The following code snippet illustrates how to create a persistent condition-based |
|
119 schedule that is triggered when both <codeph>condtion1</codeph> and <codeph>condtion2</codeph> are |
|
120 satisfied. By default, the schedule is set to start on December 10th, 2009 |
|
121 at 09:00 A.M., if the condition set is not met. </info> |
|
122 <stepxmp><codeblock id="GUID-B1F905E8-DC06-5C94-84FE-7BEC9E21EB43" xml:space="preserve">... |
|
123 |
|
124 TSchedulerItemRef& aRef; |
|
125 |
|
126 //Array to hold the schedule conditions |
|
127 CArrayFixFlat<TTaskSchedulerCondition>* cTaskScheCondArray; |
|
128 |
|
129 //Condition list to hold a set of conditions |
|
130 CSchConditionArray conditionList = new (ELeave) CSchConditionArray(2); |
|
131 CleanupStack::PushL(conditionList); |
|
132 |
|
133 //set the first condition |
|
134 TTaskSchedulerCondition condition1; |
|
135 |
|
136 //UID of the publish and subscribe category for condition1 |
|
137 const TUid KPubSubsPersistCondCategUid1 = TUid::Uid(0x102F7784); |
|
138 |
|
139 //Key of the publish and subscribe category for condition2 |
|
140 const TInt KPubSubsPersistCondKey1 = 1; |
|
141 |
|
142 condition1.iCategory = KPubSubsPersistCondCategUid1; |
|
143 condition1.iKey = KPubSubsPersistCondKey1; |
|
144 condition1.iState = 10; |
|
145 condition1.iType = TTaskSchedulerCondition::EEquals; |
|
146 conditionList->AppendL(condition1); |
|
147 |
|
148 //set the second condition |
|
149 TTaskSchedulerCondition condition2; |
|
150 |
|
151 //UID of the publish and subscribe category for condition2 |
|
152 const TUid KPubSubsPersistCondCategUid2 = TUid::Uid(0x103F7784); |
|
153 |
|
154 //Key of the publish and subscribe category for condition2 |
|
155 const TInt KPubSubsPersistCondKey2 = 1; |
|
156 |
|
157 condition2.iCategory = KPubSubsPersistCondCategUid2; |
|
158 condition2.iKey = KPubSubsPersistCondKey2; |
|
159 condition2.iState = 20; |
|
160 condition2.iType = TTaskSchedulerCondition::ENotEquals; |
|
161 conditionList->AppendL(condition2); |
|
162 |
|
163 //Set the date and time for the schedule as Dec 10th, 2009, 09:00 am |
|
164 TDateTime datetime2(2009, EDecember, 10, 9, 0, 0, 0); |
|
165 TTsTime time2(datetime2, EFalse); |
|
166 |
|
167 //create the condition-based persistent schedule |
|
168 iScheduler.CreatePersistentSchedule(aRef, *conditionList, time2); |
|
169 |
|
170 CleanupStack::PopAndDestroy(); // conditionList</codeblock> </stepxmp> |
|
171 </substep> |
|
172 <substep id="GUID-E19A594F-F7A8-576F-B509-726FB4DF3B1F"><cmd/> |
|
173 <info><xref href="GUID-B51E61E7-8A9F-354C-9695-58E741DD21AB.dita"><apiname>IMPORT_C TInt ScheduleTask(TTaskInfo& aTaskInfo, HBufC& |
|
174 aTaskData, TSchedulerItemRef& aRef, const CArrayFixFlat<TScheduleEntryInfo2>& |
|
175 aEntryList)</apiname></xref>:Creates a transient time-based schedule and adds a task |
|
176 to it. </info> |
|
177 <info>The following code snippet illustrates how to create a transient time-based |
|
178 schedule and associate a task to it. It starts at a specific time, runs every |
|
179 one hour and is valid for two hours. </info> |
|
180 <stepxmp><codeblock id="GUID-B0087E50-F2F1-5BC8-9165-53C505E53330" xml:space="preserve">... |
|
181 |
|
182 TSchedulerItemRef ref; |
|
183 |
|
184 // Array that holds the schedule entries |
|
185 CArrayFixFlat<TScheduleEntryInfo2>* cSchEntryInfoArray; |
|
186 cSchEntryInfoArray = new CArrayFixFlat<TScheduleEntryInfo2>(1); |
|
187 |
|
188 CleanupStack::PushL(cSchEntryInfoArray); |
|
189 |
|
190 // Create a schedule entry |
|
191 TScheduleEntryInfo2 entry; |
|
192 |
|
193 TTime now; |
|
194 |
|
195 // Set the date and time of this TTime to the universal time. |
|
196 now.UniversalTime(); |
|
197 |
|
198 // Assign an offset of 15 seconds. |
|
199 TInt offset = 15; |
|
200 now += TTimeIntervalSeconds(offset); |
|
201 |
|
202 // Constructs a TTsTime with a TTime object. |
|
203 // ETrue indicates that TTsTime is UTC based time |
|
204 TTsTime time(now, ETrue); |
|
205 |
|
206 // Set the above time as the first time at which |
|
207 // the entry will cause execution of tasks. |
|
208 entry.SetStartTime(time); |
|
209 |
|
210 // Set the type of interval used between due times for scheduled entry |
|
211 entry.SetIntervalType(TIntervalType(EHourly)); |
|
212 |
|
213 // Set the period for which the entry is valid. |
|
214 // After 2 hours the tasks associated with the entry will not be eligible for execution |
|
215 TInt validity = 120; |
|
216 entry.SetValidityPeriod(TTimeIntervalMinutes(validity)); |
|
217 |
|
218 // Set the interval between execution of tasks |
|
219 // Here the interval is 1 hour because the interval type is hourly. |
|
220 entry.SetInterval(1); |
|
221 |
|
222 //Add the schedule entry to the array |
|
223 cSchEntryInfoArray->AppendL(entry); |
|
224 |
|
225 // Create a transient task to be scheduled |
|
226 TTaskInfo taskInfo; |
|
227 |
|
228 // Task id |
|
229 const TInt tId = 0; |
|
230 taskInfo.iTaskId = tId; |
|
231 |
|
232 // The task repeats just once |
|
233 const TInt numberOfRepeats = 1; |
|
234 taskInfo.iRepeat = numberOfRepeats; |
|
235 |
|
236 // Task priority set by the client. |
|
237 // Where a client has two tasks with different priorities, |
|
238 // the task with the higher priority will be executed first. |
|
239 const TInt priority = 2; |
|
240 taskInfo.iPriority = priority; |
|
241 |
|
242 _LIT(KScheduleType," transient schedule"); |
|
243 const TDesC* transient = &KScheduleType; |
|
244 HBufC* data = transient->AllocLC(); |
|
245 |
|
246 // Create the transient time-based schedule |
|
247 User::LeaveIfError(iScheduler.ScheduleTask(taskInfo, *data, ref, *cSchEntryInfoArray)); |
|
248 |
|
249 ...</codeblock> </stepxmp> |
|
250 <info> Important: The task scheduler does not notify a client if a scheduled |
|
251 task fails to execute successfully. Clients can however use the notification |
|
252 mechanism of the <xref href="GUID-5B63D14D-007D-566F-A065-1A25FE4B97A3.dita">Log |
|
253 Engine</xref> to get some notification and information of the error condition |
|
254 that caused the task to fail. </info> |
|
255 <info><ul> |
|
256 <li id="GUID-CEB9D7B2-08C1-5256-8E05-743E2F894AFB"><p>Errors can occur when |
|
257 the task scheduler prepares to create and run a task process. The most likely |
|
258 error is an out of memory error. The task scheduler logs the error to the |
|
259 system log with type <xref href="GUID-3F3A8B98-D750-30C5-A2D5-D28AB1D8EAE9.dita"><apiname>KLogTaskSchedulerEventTypeUid</apiname></xref>. The |
|
260 task or schedule is not retried. </p> </li> |
|
261 <li id="GUID-11D78BC8-02F4-53C3-8544-F5C3F8BD0671"><p>If the task process |
|
262 is created successfully, but it exits with an error, the task scheduler logs |
|
263 the process exit reason to the system log, also with type <xref href="GUID-3F3A8B98-D750-30C5-A2D5-D28AB1D8EAE9.dita"><apiname>KLogTaskSchedulerEventTypeUid</apiname></xref>. </p> </li> |
|
264 </ul> </info> |
|
265 </substep> |
|
266 <substep id="GUID-8E8365D3-3A08-5B6E-BA92-73F2E750145C"><cmd/> |
|
267 <info> <xref href="GUID-C6D23376-3EF2-349A-9BCF-812D57E61EA3.dita"><apiname>IMPORT_C TInt ScheduleTask(TTaskInfo& aTaskInfo, HBufC& |
|
268 aTaskData, TSchedulerItemRef& aRef, const CArrayFixFlat<TTaskSchedulerCondition>& |
|
269 aConditions, const TTsTime& aDefaultRunTime)</apiname></xref>: Creates a transient |
|
270 condition-based schedule and adds a task to it. </info> |
|
271 <info>The following code snippet illustrates how to create a transient condition-based |
|
272 schedule and associate a task to it. The schedule is triggered when <codeph>condition1</codeph> is |
|
273 met. By default, the schedule is set to start on December 10th, 2009 at 09:00 |
|
274 A.M., if the condition set is not met. </info> |
|
275 <stepxmp><codeblock id="GUID-F1E856BD-38F2-5F65-B1D7-96B11A008F47" xml:space="preserve">... |
|
276 |
|
277 TSchedulerItemRef ref2; |
|
278 |
|
279 //Array that holds the conditions |
|
280 CArrayFixFlat<TTaskSchedulerCondition>* CSchConditionArray; |
|
281 CSchConditionArray conditionList = new (ELeave) CSchConditionArray(1); |
|
282 |
|
283 CleanupStack::PushL(conditionList); |
|
284 |
|
285 //set the condition |
|
286 TTaskSchedulerCondition condition1; |
|
287 |
|
288 //UID of the publish and subscribe category for condition1 |
|
289 const TUid KPubSubsTransCondCategUid1 = TUid::Uid(0x102F7785); |
|
290 |
|
291 //Key of the publish and subscribe category for condition1 |
|
292 const TInt KPubSubsTransCondKey1 = 1; |
|
293 |
|
294 condition1.iCategory = KPubSubsTransCondCategUid1; |
|
295 condition1.iKey = KPubSubsTransCondKey1; |
|
296 condition1.iState = 10; |
|
297 condition1.iType = TTaskSchedulerCondition::EEquals; |
|
298 conditionList->AppendL(condition1); |
|
299 |
|
300 // Associate a task with the condition-based schedule |
|
301 TTaskInfo taskInfo2; |
|
302 |
|
303 _LIT(KTransSchedTaskName, "Transient - Condition-Based"); |
|
304 _LIT(KTransSchedTaskData2, "Task data for transient schedule"); |
|
305 |
|
306 taskInfo2.iName = KTransSchedTaskName; |
|
307 taskInfo2.iPriority = 2; |
|
308 taskInfo2.iRepeat = 0; |
|
309 |
|
310 // Create some data associated with this task |
|
311 HBufC* taskTransSchedData = KTransSchedTaskData2().AllocLC(); |
|
312 |
|
313 //set the default time at which you want the transient condition-based |
|
314 //schedule to start, if no conditions are met |
|
315 // sets the date and time as Jan 1st, 2010, 10:01 am |
|
316 TDateTime datetime2(2010, EJanuary, 1, 10, 1, 0, 0); |
|
317 TTsTime defaultRuntime(datetime2, ETrue); // 10:01 am |
|
318 |
|
319 // Create the transient condition-based schedule |
|
320 User::LeaveIfError(iScheduler.ScheduleTask(taskInfo2, *taskTransSchedData, ref2, *conditionList, defaultRuntime)); |
|
321 |
|
322 CleanupStack::PopAndDestroy(2); // taskTransSchedData, conditionList |
|
323 |
|
324 ...</codeblock> </stepxmp> |
|
325 </substep> |
|
326 </substeps> |
|
327 <info><note> Schedules can be either persistent or transient. Persistent schedules |
|
328 have schedule information and any corresponding task data persisted to the |
|
329 disk. </note></info> |
|
330 <info>The task scheduler server reads this data back into memory when the |
|
331 phone is restarted. But, transient schedules do not have their data persisted |
|
332 and are deleted automatically once any associated tasks have finished running. </info> |
|
333 </step> |
|
334 <step id="GUID-265E13BF-EC53-5308-ABD1-92FAF2F3A9E0"><cmd/> |
|
335 <info>Create the support for adding tasks to a persistent schedule by passing |
|
336 the handle of the persistent schedule to <xref href="GUID-A293C22A-B2A7-333B-B2B7-E28A22343DE9.dita"><apiname>ScheduleTask(TTaskInfo& |
|
337 aTaskInfo, HBufC& aTaskData, const TInt aScheduleHandle)</apiname></xref>. </info> |
|
338 <info><b> Notes</b>: <ul> |
|
339 <li><p>This step applies only, if you have already created a persistent schedule. </p></li> |
|
340 <li><p>For more information about the effects of backup and restore on scheduled |
|
341 tasks in persistent schedules, see the <xref href="GUID-00363030-AAE2-5231-8407-AC609DA0F496.dita">Backup |
|
342 and Restore on Scheduled Tasks in Persistent Schedules</xref>. </p></li> |
|
343 </ul><p/></info> |
|
344 <info>The following code snippet illustrates how to create a task and associate |
|
345 it with an existing persistent schedule. </info> |
|
346 <stepxmp><codeblock id="GUID-BA89C9FD-0876-59CE-BD90-BBEE3526277F" xml:space="preserve"> |
|
347 ... |
|
348 |
|
349 //Contains the handle to the persistent schedule |
|
350 TInt aScheduleId; |
|
351 ... |
|
352 |
|
353 |
|
354 TInt& aNewId; |
|
355 |
|
356 //Create the task that you want to add the persistent schedule |
|
357 TTaskInfo taskInfo; |
|
358 taskInfo.iTaskId = aNewId; |
|
359 |
|
360 _LIT(aName, "Task for Persistent Schedule"); |
|
361 |
|
362 taskInfo.iName = aName; |
|
363 taskInfo.iPriority = 2; |
|
364 taskInfo.iRepeat = 0; |
|
365 |
|
366 HBufC* taskdata = _L("the data").AllocLC(); |
|
367 |
|
368 iScheduler.ScheduleTask(taskInfo, *taskdata, aScheduleId); |
|
369 |
|
370 //Update aNewId with the task ID set by the task scheduler |
|
371 aNewId = taskInfo.iTaskId; |
|
372 ... |
|
373 |
|
374 CleanupStack::PopAndDestroy(); // taskdata |
|
375 |
|
376 ...</codeblock> </stepxmp> |
|
377 <info> Notes: </info> |
|
378 <info><p><ul> |
|
379 <li><p>The <codeph>HBufC* taskdata</codeph> parameter is used by clients who |
|
380 want to send data to the executable that is launched when the task becomes |
|
381 due. When the executable is launched, this data is stored in a temporary task |
|
382 file and the filename is passed on the command line to the newly created process. |
|
383 That executable can then open the file and stream in the contents. </p></li> |
|
384 <li><p>If multiple tasks are assigned to a schedule that has become due, the |
|
385 data for each schedule is concatenated into the same file. The tasks are stored |
|
386 in the file as <xref href="GUID-049FF2D7-8444-3E87-BF2F-DD0EA9B10ED0.dita"><apiname>CScheduledTask</apiname></xref> instances. The first item |
|
387 in the file is an integer describing how many tasks there are in the file. |
|
388 Subsequently the file just contains tasks which can be streamed in using the <xref href="GUID-049FF2D7-8444-3E87-BF2F-DD0EA9B10ED0.dita#GUID-049FF2D7-8444-3E87-BF2F-DD0EA9B10ED0/GUID-F9ED1FDD-0DAF-3450-99A6-730D43D00FE0"><apiname>CScheduledTask::NewLC()</apiname></xref> method. </p></li> |
|
389 </ul></p></info> |
|
390 </step> |
|
391 <step id="GUID-DEE8E40C-ED35-5C48-9406-DA44B1E68A61"><cmd/> |
|
392 <info>Create the support for viewing schedules. This involves two steps: </info> |
|
393 <substeps id="GUID-97888525-CEB8-530F-A092-5DB980E7C841"> |
|
394 <substep id="GUID-B783CD9D-AE70-5BB9-B6ED-CC93EEE97512"><cmd/> |
|
395 <info>Get the name and ID (schedule handle) of schedules using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-7C8B221C-F8E5-3EEE-9693-2055D6F1EBF4"><apiname>RScheduler::GetScheduleRefsL()</apiname></xref>. </info> |
|
396 <stepxmp><codeblock id="GUID-07058B0D-CD00-53A0-B744-6073FD81B941" xml:space="preserve">//Array that holds schedule entries |
|
397 CArrayFixFlat<TSchedulerItemRef>* CSchItemRefArray; |
|
398 CSchItemRefArray = new CArrayFixFlat<TSchedulerItemRef>(3); |
|
399 |
|
400 CleanupStack::PushL(CSchItemRefArray); |
|
401 |
|
402 //Get the list of all schedules |
|
403 User::LeaveIfError(iScheduler.GetScheduleRefsL(*CSchItemRefArray, EAllSchedules)); |
|
404 |
|
405 ... |
|
406 |
|
407 //Gets the schedule handle and assigns it to schedHandle |
|
408 TInt schedHandle = *CSchItemRefArray)[1].iHandle; |
|
409 |
|
410 ...</codeblock> </stepxmp> |
|
411 </substep> |
|
412 <substep id="GUID-5D034701-EF62-5982-8070-A2C40DDD1122"><cmd/> |
|
413 <info>Get schedule details by passing the schedule handle to <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-AD5F8784-D619-32BB-B125-30C7393FA1A9"><apiname>RScheduler::GetScheduleL()</apiname></xref> or <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-946F7B2F-EF2C-33DB-A397-D31A009165A6"><apiname>RScheduler::GetScheduleTypeL()</apiname></xref>. </info> |
|
414 <info><ul> |
|
415 <li id="GUID-D15FBE3E-4214-5074-A91C-747324339C7E"><p> <b>Viewing details |
|
416 of time-based schedules:</b> </p> <codeblock id="GUID-27955B2E-A6F6-5D13-8AFD-7AC37F579E31" xml:space="preserve">... |
|
417 |
|
418 CArrayFixFlat<TTaskInfo> CTaskInfoArray; |
|
419 CTaskInfoArray* tasks = new (ELeave) CTaskInfoArray(3); |
|
420 |
|
421 TTsTime nextTimeScheduleIsDue; |
|
422 TScheduleState2 stateTimebasedSched; |
|
423 |
|
424 CArrayFixFlat<TScheduleEntryInfo2> CScheduleEntryInfoArray; |
|
425 CScheduleEntryInfoArray* entries = new (ELeave) CScheduleEntryInfoArray(3); |
|
426 |
|
427 CleanupStack::PushL(entries); |
|
428 |
|
429 iScheduler.GetScheduleL(schedHandle, stateTimebasedSched, *entries, tasks, nextTimeScheduleIsDue); |
|
430 CleanupStack::PopAndDestroy(entries);</codeblock> </li> |
|
431 <li id="GUID-5EBF8371-0DAB-5C02-93BE-84C75D2258A3"><p> <b>Viewing details |
|
432 of condition-based schedules:</b> </p> <codeblock id="GUID-240EF5BE-211F-5CA4-AD03-0A39B7FD9927" xml:space="preserve">... |
|
433 |
|
434 TTsTime defaultTime; |
|
435 TScheduleState2 state; |
|
436 |
|
437 CArrayFixFlat<TTaskInfo> CTaskInfoArray; |
|
438 CTaskInfoArray* tasks = new (ELeave) CTaskInfoArray(3); |
|
439 |
|
440 CArrayFixFlat<TTaskSchedulerCondition> CSchConditionArray; |
|
441 CSchConditionArray* conditionList = new (ELeave) CSchConditionArray(3); |
|
442 CleanupStack::PushL(conditionList); |
|
443 |
|
444 iScheduler.GetScheduleL(schedHandle, state, *conditionList, defaultTime, tasks); |
|
445 |
|
446 CleanupStack::PopAndDestroy(conditionList);</codeblock> </li> |
|
447 <li id="GUID-9966127B-4650-510D-9FD4-36177F801889"><p> <b>Viewing the schedule |
|
448 type associated with a schedule:</b> Identifies whether the schedule is a |
|
449 condition or time-based. </p> <codeblock id="GUID-E696A2CA-3135-56BD-8B41-AE2CB5E6FDC0" xml:space="preserve">... |
|
450 |
|
451 TScheduleType &type; |
|
452 |
|
453 iScheduler.GetScheduleTypeL(schedHandle, type);</codeblock> </li> |
|
454 </ul> </info> |
|
455 </substep> |
|
456 </substeps> |
|
457 </step> |
|
458 <step id="GUID-BA59B4AB-0104-5794-808E-5D9F6693BE03"><cmd/> |
|
459 <info>Create the support for editing, enabling and disabling schedules. Schedules |
|
460 can be edited using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-50B287A9-F62F-3C49-AD22-2760C96846EA"><apiname>RScheduler::EditSchedule()</apiname></xref> when a change |
|
461 is required to be done to a schedule. </info> |
|
462 <info>Before making changes to a schedule, you can use <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-64263B93-74B9-3526-B585-4B2E8B8B86A2"><apiname>RScheduler::DisableSchedule()</apiname></xref> to |
|
463 disable a schedule, so that it is not triggered and later use <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-5AE06AE8-46BA-3339-8ADB-E7C642928C9C"><apiname>RScheduler::EnableSchedule()</apiname></xref> to |
|
464 enable it, once the changes are done to the schedule. </info> |
|
465 <info>The following code snippet illustrates how to disable a time-based schedule, |
|
466 edit it to make changes to the schedule and later enable the schedule. </info> |
|
467 <stepxmp><codeblock id="GUID-BD180A79-767B-54A4-A5EA-4D763A295D4C" xml:space="preserve">//Editing time-based schedules |
|
468 |
|
469 ... |
|
470 |
|
471 TInt schedHandle; |
|
472 |
|
473 ... |
|
474 |
|
475 //Disables the schedule referenced by "schedHandle" |
|
476 User::LeaveIfError(iScheduler.DisableSchedule(schedHandle); |
|
477 ... |
|
478 |
|
479 //Array to hold the schedule entries |
|
480 CArrayFixFlat<TScheduleEntryInfo2> CSchEntryInfoArray; |
|
481 CSchEntryInfoArray* entryList = new (ELeave) CSchEntryInfoArray(3); |
|
482 |
|
483 CleanupStack::PushL(entryList); |
|
484 |
|
485 //Change the start date and time as Jan 10th, 2010, 11:00 am |
|
486 TDateTime datetime2(2010, EJanuary, 10, 11, 0, 0, 0); |
|
487 TTsTime defaultRuntime(datetime2, ETrue); |
|
488 |
|
489 //create the schedule entry with the updated time |
|
490 TScheduleEntryInfo2 entry1 (defaultRuntime, EDaily, 1, 20); // 20m from "now" |
|
491 entryList->AppendL(entry1); |
|
492 |
|
493 //Enables the schedule referenced by "schedHandle" |
|
494 User::LeaveIfError(iScheduler.EnableSchedule(schedHandle); |
|
495 |
|
496 //edit the schedule |
|
497 User::LeaveIfError(iScheduler.EditSchedule(schedHandle, entryList)); |
|
498 |
|
499 CleanupStack::PopAndDestroy(entryList);</codeblock> </stepxmp> |
|
500 <info>The following code snippet illustrates how to edit a condition-based |
|
501 schedule by passing the schedule handle of the schedule to be edited and the |
|
502 updated schedule condition details to <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-50B287A9-F62F-3C49-AD22-2760C96846EA"><apiname>RScheduler::EditSchedule()</apiname></xref>. </info> |
|
503 <stepxmp><codeblock id="GUID-35B0F192-2530-5BD4-8AF5-E44C02405D13" xml:space="preserve">//Editing condition-based schedules |
|
504 ... |
|
505 |
|
506 TInt schedHandle; |
|
507 |
|
508 ... |
|
509 |
|
510 CArrayFixFlat<TTaskSchedulerCondition>* CSchConditionArray; |
|
511 |
|
512 |
|
513 CSchConditionArray conditionList = new (ELeave) CSchConditionArray(2); |
|
514 CleanupStack::PushL(conditionList); |
|
515 |
|
516 //update the condition |
|
517 TTaskSchedulerCondition condition1; |
|
518 |
|
519 //UID of the publish and subscribe category for condition1 |
|
520 const TUid KPubSubsTransCondCategUid1 = TUid::Uid(0x102F7785); |
|
521 |
|
522 //Key of the publish and subscribe category for condition1 |
|
523 const TInt KPubSubsTransCondKey1 = 1; |
|
524 |
|
525 condition1.iCategory = KPubSubsTransCondCategUid1; |
|
526 condition1.iKey = KPubSubsTransCondKey1; |
|
527 condition1.iState = 10; |
|
528 condition1.iType = TTaskSchedulerCondition::EEquals; |
|
529 conditionList->AppendL(condition1); |
|
530 |
|
531 // sets the date and time as Jan 10th, 2010, 10:00 am |
|
532 TDateTime datetime2(2010, EJanuary, 10, 10, 0, 0, 0); |
|
533 TTsTime defaultRuntime(datetime2, ETrue); |
|
534 |
|
535 iScheduler.EditSchedule(schedHandle, *conditionList, defaultRuntime); |
|
536 |
|
537 ...</codeblock> </stepxmp> |
|
538 </step> |
|
539 <step id="GUID-91C5C26A-7120-500C-8F42-AE61133BB375"><cmd/> |
|
540 <info>Create the support for deleting schedules using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-B4CECD92-82C6-3CEC-8DA6-E4D1580BEC00"><apiname>RScheduler::DeleteSchedule()</apiname></xref>. </info> |
|
541 <stepxmp><codeblock id="GUID-DBB6A497-BFFC-5832-B5E8-5B8D2F713576" xml:space="preserve">... |
|
542 |
|
543 //Deletes the schedule referenced by "schedHandle" |
|
544 iScheduler.DeleteSchedule(schedHandle);</codeblock> </stepxmp> |
|
545 </step> |
|
546 <step id="GUID-83E497A5-9C7C-5B57-A4E1-922A0B9BF913"><cmd/> |
|
547 <info>Create the support for viewing task information associated with a schedule. |
|
548 This involves two steps: </info> |
|
549 <substeps id="GUID-F7C63AE4-4F06-58A6-9614-BC5356176977"> |
|
550 <substep id="GUID-89600927-D804-54C6-8C97-459BD3C1078E"><cmd/> |
|
551 <info>Get a list of all tasks or a subset of tasks using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-8A56C5D7-473C-3CA1-9B03-E6C794434EAB"><apiname>RScheduler::GetTaskRefsL()</apiname></xref>. </info> |
|
552 <stepxmp><codeblock id="GUID-6EA170CE-2CE5-5E43-B9AA-3FC177BF1B3F" xml:space="preserve">//Array to hold the list of tasks |
|
553 CArrayFixFlat<TSchedulerItemRef> CSchItemRefArray; |
|
554 CSchItemRefArray* refs = new (ELeave) CSchItemRefArray(3); |
|
555 |
|
556 //Gets the list of tasks |
|
557 iScheduler.GetTaskRefsL(*refs, EAllSchedules, EAllTasks); |
|
558 |
|
559 CleanupStack::PopAndDestroy(refs);</codeblock> </stepxmp> |
|
560 </substep> |
|
561 <substep id="GUID-242AEAF8-CC8B-5EA3-9394-A62F79275735"><cmd/> |
|
562 <info>Get details associated with a specific task using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-389F77C6-6127-3376-B4CF-993A5849903B"><apiname>RScheduler::GetTaskInfoL()</apiname></xref>. </info> |
|
563 <stepxmp><codeblock id="GUID-8EB737CE-5990-5A04-8A44-CA1B3EDB82DE" xml:space="preserve">... |
|
564 |
|
565 //Handle to the task |
|
566 TInt aTaskHandle; |
|
567 |
|
568 ... |
|
569 |
|
570 TInt taskSize = 0; |
|
571 |
|
572 //Gets the size of the data to be passed to the task's program. |
|
573 taskSize = iScheduler.GetTaskDataSize(aTaskHandle, taskSize); |
|
574 HBufC* taskData = HBufC::NewLC(taskSize); |
|
575 |
|
576 TPtr pTaskData = taskData->Des(); |
|
577 |
|
578 TTsime scheduleNextDueTime; |
|
579 TTaskInfo taskFromServer; |
|
580 TSchedulerItemRef scheduleReference; |
|
581 |
|
582 //Gets task details |
|
583 iScheduler.GetTaskInfoL(aTaskHandle, taskFromServer, pTaskData, scheduleReference, scheduleNextDueTime); |
|
584 |
|
585 CleanupStack::PopAndDestroy(taskData);</codeblock> </stepxmp> |
|
586 </substep> |
|
587 </substeps> |
|
588 </step> |
|
589 <step id="GUID-85E5D82C-B280-57D3-89E2-7AC8C63C072C"><cmd/> |
|
590 <info>Create the support for deleting tasks associated with a schedule using <xref href="GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1.dita#GUID-6E138B87-ED51-3C72-9075-8D7F887FA7B1/GUID-BE934053-79EA-3101-899D-18BC91359BB7"><apiname>RScheduler::DeleteTask()</apiname></xref>. </info> |
|
591 <stepxmp><codeblock id="GUID-ADF28359-38D9-5B32-8828-929E4AE56496" xml:space="preserve">TInt taskId; |
|
592 |
|
593 ... |
|
594 |
|
595 iScheduler.DeleteTask(taskId);</codeblock> </stepxmp> |
|
596 </step> |
|
597 </steps> |
|
598 </taskbody><related-links> |
|
599 <link href="GUID-3CDCE4E0-E29D-5782-8053-B386A9E34BCC.dita"><linktext>Task Scheduler |
|
600 Overview</linktext></link> |
|
601 <link href="GUID-00363030-AAE2-5231-8407-AC609DA0F496.dita"><linktext>Backup and |
|
602 Restore on Scheduled Tasks in Persistent Schedules</linktext></link> |
|
603 </related-links></task> |