Tasker2 is a tool to launch or kill applications periodically using windows mobile scheduler. It was born to control the running of agent software on windows mobile at specified times. The problem with the agent software was that it does not open/close connections only on usage times but all the time and the device’s battery was drain very fast. We decided to write a helper that would launch and kill the agent to have it running only within a defined time frame.
Background process
We could have written a background process to run external tasks periodically. But the main disadvantage of timers and threads in background processes is that they do not run, if the device is in suspend mode.
To ensure that tasks will be launched also if the device is sleeping, we decided to use the windows mobile scheduler. There are functions inside the notification API to create notifications that will run an application at a specified time. This is what we call a schedule.
The scheduler (notification API)
After a timed schedule has been done by the scheduler, the schedule is removed from the notification database. If you like to have a periodic schedule, you have to ensure that a new schedule is created inside your code.
Pitfalls
During development we found many pitfalls in conjunction with the windows mobile scheduler. This is why I decided to write this post.
The tasks
Tasker2 is a console application without any GUI but it will write a log with all you need to know. Tasker2 supports up to ten tasks. A task is defined using the registry. Every task has an entry for start and stop times, the application to control, an interval for the schedule and a flag for control if a task is only to be run on external power:
REGEDIT4
[HKLM\Software\Tasker\Task1]
"active":DWORD=1
"exe":="\Windows\fexplore.exe"
"arg":="\My Documents"
"start":="1423"
"stop":="1523"
"interval":="2400"
"startOnAConly":DWORD=0;
active: if active is 0, tasker2 will not kill or start the process
exe: name of the process executable to start or kill
arg: arguments to be when launching the executable
start: when to start the executable the next time
stop: when to kill the process the next time
interval: when a start or kill has been executed, tasker2 will create a new schedule using this interval. If the interval is “0010″, the start process will be scheduled for every 10 minutes.
startOnAConly: if 1 and when a process has to be started, the process will only be started if the device is on external power
The scheduler
First, tasker2 is normally only launched one time manually and all future calls are made by the scheduler. Tasker2 will clear and schedule all planned tasks as defined in the registry if it is launched without arguments.
The scheduler is a task manager running all the time in windows mobile. If a timed schedule is reached, the scheduler will launch the specified application, see also here . This will also work if the device is in suspend mode (sleeps). The scheduler can also fire on special events like time or hardware changes (ON_RS232_CONNECT for example). See also my post here [http://www.hjgode.de/wp/2010/03/06/irunatevent/].
Theory of operation
Tasker2 uses command line arguments to control itself. The scheduler launches tasker2 with the specified arguments and tasker2 will then run or kill the defined task.
Delayed schedules (pitfall 1)
If your device supports a real power down, the scheduler will not awake the device and is not able to launch the defined schedules. When the device is later powered on, it will schedule all past schedules at once. This is what we call a ‘delayed schedule’ and a flooding of launches. Flooding in the mean of many schedules of tasker2 occurring at the same time for past tasks.
To avoid concurrent changes to the registry and scheduler entries, tasker2 uses a mutex to ensure only one instance is continuing execution. Subsequent instances will wait for existing instances before they do there work.
<ol><li class="li1"><div class="de1">
On a delayed, flooding schedule ALL pending tasks are scheduled and possibly a Time_Changed string is sent to the pending tasks. This flooding will be serialized as tasker2 waits for existing tasker2 instances.
Time and time zone changes (pitfall 2)
When the time is changed on the device, the scheduler will inform all timed tasks. Tasker2 must then recalculate new schedules based on current local time. The scheduler launches the defined applications with the TIME_CHANGED string as argument.
<ol><li class="li1"><div class="de1">else if(wcsicmp(argv[1], APP_RUN_AFTER_TIME_CHANGE)==0 || wcsicmp(argv[1], APP_RUN_AFTER_TZ_CHANGE)==0){</div></li><li class="li1"><div class="de1"> nclog(L"got '%s' signaled\n", argv[1]);</div></li><li class="li1"><div class="de1"> Additionally we found that the time changes may also occur during program launch or as tasker2 instances wait for another tasker2 instance. So tasker2 uses only one (in real two) calls to get the current time. This is essential, as tasker2 uses the current time to re-schedule tasks. The current time is called at the beginning, before tasker2 waits for the mutex. This is the time tasker2 was launched. If there has been a time_changed schedule, tasker2 will use another call to the current time, as it may have changed between the launch and the further execution of the code – after the mutex is released and the current instance is allowed to run.
Delayed schedules II (pitfall 3)
As only one instance of tasker2 is executing, it may happen, that the current time and the task time do not match exactly. Although the scheduler may do its best to launch tasker2 at the right time, the execution may be delayed in regards of the time the task is to be scheduled and the current time. This is another delayed schedule compared to the above flooding of schedules after a power down/up cycle.
It may also happen that a lot of tasker2 instances are waiting for execution, you know that we can have up to ten tasks. This may also lead to ‘delayed’ code execution, but should be in a small time frame of some minutes only.
Therefor tasker2 supports a maximum allowed delay time to distinguish between allowed and flooding delayed calls.
<ol><li class="li1"><div class="de1">
Adding a schedule
I am using central functions in code to add or remove schedules. Here is a sample of how a schedule is added:
<ol><li class="li1"><div class="de1">...</div></li><li class="li1"><div class="de1">#include "notify.h"</div></li><li class="li1"><div class="de1">...</div></li><li class="li1"><div class="de1">
The main code
The main function is processStartStopCmd() beside createNextSchedule(). It does all the scheduling and time calculations.
<ol><li class="li1"><div class="de1"></div></li><li class="li1"><div class="de1">
Tasker2 control
Although you normally dont need to run tasker2 manually, I have added some command line arguments:
“-c” instructs tasker2.exe to remove all tasker2 schedules of the scheduler database
“-r taskX” deactivate processing of task with number X, sets the active flag to 0
“-a taskX” activate processing of task number X, sets the active flag to 1
“-d” dump a list of all active notifications of the windows mobile scheduler
Do not use -s taskX and -k taskX except for testing. The args ‘-s taskX’ and ‘-k taskX’ are only be used by the scheduler.
Log file
The log file will log all activities of tasker2 in the directory of tasker2.exe. It will grow until 1MB and then one log backup file is saved. So you may have two log files, one active and one backup of the previous log.
<ol><li class="li1"><div class="de1">0xfacbcab2: ++++++++++++++++ Tasker v300 started +++++++++++++++++++</div></li><li class="li1"><div class="de1">0xfacbcab2: Checking <a href="http://www.ss64.com/nt/for.html">for</a> Mutex (single instance allowed only)...</div></li><li class="li1"><div class="de1">0xfacbcab2: Created new mutex</div></li><li class="li1"><div class="de1">0xfacbcab2: ~~~ using actual localtime:</div></li><li class="li1"><div class="de1">0xfacbcab2: 23.12.2011, 12:28</div></li><li class="li1"><div class="de1">0xfacbcab2: CmdLine =</div></li><li class="li1"><div class="de1">0xfacbcab2: Checking <a href="http://www.ss64.com/nt/for.html">for</a> valid date/time...</div></li><li class="li1"><div class="de1">0xfacbcab2: Date/Time after 11 2011. OK</div></li><li class="li1"><div class="de1">0xfacbcab2: Clearing Event Notifications...0xfacbcab2: OK</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): ...</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3d00000f</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x33000025</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3800002a</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3b00001b</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3800002e</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3f00001e</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x37000016</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): CeClearUserNotification <a href="http://www.ss64.com/nt/for.html">for</a> handle: 0x3a000030</div></li><li class="li1"><div class="de1">0xfacbcab2: ClearRunApp(): returns 8</div></li><li class="li1"><div class="de1">0xfacbcab2: Cleared 8 Tasker schedules</div></li><li class="li1"><div class="de1">0xfacbcab2: scheduleAllTasks: ClearAllSchedules <a href="http://www.ss64.com/nt/for.html">for</a> 8 tasks</div></li><li class="li1"><div class="de1">0xfacbcab2: Clearing Event Notifications...0xfacbcab2: Clearing Event Notifications...0xfacbcab2: OK</div></li><li class="li1"><div class="de1">0xfacbcab2: Adding Time_Change Event Notification...0xfacbcab2: OK</div></li><li class="li1"><div class="de1">0xfacbcab2: Adding TZ_Change Event Notification...0xfacbcab2: OK</div></li><li class="li1"><div class="de1">0xfacbcab2: Creating new Start Task schedule <a href="http://www.ss64.com/nt/for.html">for</a> '\Windows\notes.exe' <a href="http://www.ss64.com/nt/in.html">in</a> Task1</div></li><li class="li1"><div class="de1">0xfacbcab2: calculating new schedule <a href="http://www.ss64.com/nt/for.html">for</a> '201112231300'...</div></li><li class="li1"><div class="de1">0xfacbcab2: interval is: 0d01h00m</div></li><li class="li1"><div class="de1">0xfacbcab2: schedule adjusted to '201112231300'</div></li><li class="li1"><div class="de1">0xfacbcab2: ScheduleRunApp: Next run at: 23.12.2011 13:00:56</div></li><li class="li1"><div class="de1">0xfacbcab2: ScheduleRunApp: CeSetUserNotificationEx succeeded...</div></li><li class="li1"><div class="de1">0xfacbcab2: Creating new Kill Task schedule <a href="http://www.ss64.com/nt/for.html">for</a> '\Windows\notes.exe' <a href="http://www.ss64.com/nt/in.html">in</a> Task1</div></li><li class="li1"><div class="de1">0xfacbcab2: calculating new schedule <a href="http://www.ss64.com/nt/for.html">for</a> '201112231300'...</div></li><li class="li1"><div class="de1">0xfacbcab2: interval is: 0d01h00m</div></li><li class="li1"><div class="de1">0xfacbcab2: schedule adjusted to '201112231300'</div></li><li class="li1"><div class="de1">0xfacbcab2: ScheduleRunApp: Next run at: 23.12.2011 13:00:56</div></li><li class="li1"><div class="de1">0xfacbcab2: ScheduleRunApp: CeSetUserNotificationEx succeeded...</div></li><li class="li1"><div class="de1">...</div></li></ol>
The first entry in the log file is the current logging instance. As multiple instances may write randomly at the log, the instance number is needed to idetify which instance has written the current log line.
Changes
There are two variants of tasker2, one is using SYSTEMTIME and the other, new one uses time_t. I switched to time_t as it is more easy to do operations like add-one-day with time_t vars than with SYSTEMTIME.
The old variant (v234a) is available as a branch in the code repository: http://code.google.com/p/tasker2/source/browse/#svn%2Fbranch%2Fversion232%2FTasker
Tests
Fortunately I had great help by a tester of the software. Many thanks to Thomas B.
I built my only automatic test suite using batch files and a special build of tasker2.exe. If you uncomment the line //#define TESTMODE at the beginning of tasker2.cpp, the compiled app will be in test mode. That means it will not add or remove schedules to/from the windows mobile scheduler. There is another tool used in the test_run.bat that sets the date and time of the device remotely (ActiveSync or Windows Mobile Device Center connection).
The automatic test uses the great tools of itsutils and will set registry values, change date/time, launch tasker2, get the log and build a merged log with all essential data to check the function of tasker2:
http://code.google.com/p/tasker2/source/browse/#svn%2Ftrunk%2FTasker%2Ftest
Here is a snippet from the test_bat.bat:
<ol><li class="li1"><div class="de1">@echo off</div></li><li class="li1"><div class="de1"> </div></li><li class="li1"><div class="de1">ECHO ############## START ###############</div></li><li class="li1"><div class="de1">echo MAKE SHURE THE RADIOS ARE OFF TO</div></li><li class="li1"><div class="de1">echo AVOID AUTOMATIC <a href="http://www.php.net/time">TIME</a> SYNCS!</div></li><li class="li1"><div class="de1">echo .</div></li><li class="li1"><div class="de1">PAUSE Press any <a href="http://www.php.net/key">key</a> to start</div></li><li class="li1"><div class="de1"> </div></li><li class="li1"><div class="de1">ECHO ############## START ############### >test_run.txt</div></li><li class="li1"><div class="de1"> </div></li><li class="li1"><div class="de1">echo Importing test reg keys...</div></li><li class="li1"><div class="de1">echo Importing test reg keys... >>test_run.txt</div></li><li class="li1"><div class="de1">pregutl @tasker2.reg >>test_run.txt</div></li><li class="li1"><div class="de1"> </div></li><li class="li1"><div class="de1">pdel \tasker2.exe.<a href="http://www.php.net/log">log</a>.txt >NUL</div></li><li class="li1"><div class="de1">pput -f ./tasker2.exe \tasker2.exe</div></li><li class="li1"><div class="de1"> </div></li><li class="li1"><div class="de1">ECHO TEST1...</div></li><li class="li1"><div class="de1">ECHO set <a href="http://www.php.net/time">time</a> manually to 01.01.2003 12:00</div></li><li class="li1"><div class="de1">echo run tasker2.exe</div></li><li class="li1"><div class="de1">ECHO ++++++++++++++ TEST1 ++++++++++++++++ >>test_run.txt</div></li><li class="li1"><div class="de1">pregutl HKLM\Software\Tasker >>test_run.txt</div></li><li class="li1"><div class="de1">ECHO ------------------------------------- >>test_run.txt</div></li><li class="li1"><div class="de1">ECHO set <a href="http://www.php.net/time">time</a> manually to 01.01.2003 12:00 >>test_run.txt</div></li><li class="li1"><div class="de1">ECHO ------------------------------------- >>test_run.txt</div></li><li class="li1"><div class="de1">prun \SetDateTime.exe 200301011200</div></li><li class="li1"><div class="de1">CALL :MYWAIT</div></li><li class="li1"><div class="de1">prun \tasker2.exe</div></li><li class="li1"><div class="de1">ECHO "############# Result:" >>test_run.txt</div></li><li class="li1"><div class="de1">pregutl HKLM\Software\Tasker >>test_run.txt</div></li><li class="li1"><div class="de1">ECHO *************** <a href="http://www.php.net/log">LOG</a> **************** >>test_run.txt</div></li><li class="li1"><div class="de1">pget -f \tasker2.exe.<a href="http://www.php.net/log">log</a>.txt</div></li><li class="li1"><div class="de1">type tasker2.exe.<a href="http://www.php.net/log">log</a>.txt >>test_run.txt</div></li><li class="li1"><div class="de1">pdel \tasker2.exe.<a href="http://www.php.net/log">log</a>.txt</div></li><li class="li1"><div class="de1">ECHO ---------------TEST1 --------------- >>test_run.txt</div></li><li class="li1"><div class="de1">ECHO .>>test_run.txt</div></li></ol>
Downloads
The full tasker2 source code is available at http://code.google.com/p/tasker2/source/browse
Tool to look at the scheduler database [NotificationList]: DOWNLOAD:NotificationList - A tool to list notifications (Hits: 1, size: 153.42 kB)
<!-- Social Bookmarks BEGIN -->
<!-- Social Bookmarks END -->
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
