Basic class for using the Microsoft Task Scheduler

Overview

Microsoft developed a full-featured scheduler for IE 4, IE 5, Win 98, and NT 5. From looking at all the task options available (three property pages, plus an "advanced" dialog) you could imagine that programming the scheduler is quite a chore. And you'd be right. I developed the CScheduledTask class to help you create very simple tasks and understand the basics of using the scheduler.

View changes and bug fixes.

There is plenty of room for improvement in this class. This was done purposely on my part -- making a class to implement all the features of the scheduler would have amounted to rewriting the scheduler UI, which I really didn't want to do (for free ;)). As it currently stands, CScheduledTask can create and delete events from the scheduler. Tasks can have simple schedules, namely one time only, daily, weekly, or monthly.

CScheduledTask was written with MSVC 6.0 on Win 98. It should work OK in Unicode, although I haven't tested it. I do use a couple of 6.0-specific functions, such as CTime::GetAsSystemTime() and CString::Delete(), so in order to build with MSVC 5.0, you'd need to convert those sections back to use MFC 4.2 functions. You would also need the INetSDK or Platform SDK installed, because you need to link with MSTASK.LIB for the scheduler GUIDs and #include MSTASK.H for the interfaces.

Please note that this class does not interface with the AT service, the default scheduler on NT 4 and earlier.

Creating a task

So, you want to schedule a program, eh? Here is the information you'll need to provide to CScheduledTask:

• Program name: The fully-qualified path to the program (required).
• Parameters: Any command-line parameters you want to pass to the program (optional).
• Starting directory: The starting directory for the program (optional).
• Account and password: The account the task will run under, and the account's password (required for NT only).
• Starting date and time: The date and time a one-time task will run, or the beginning date and time for a repeating task (required).
• Ending date: The last day that a repeating task will run (optional, N/A for one-time tasks). If this is not set for a repeating task, the task will repeat indefinitely.
• Frequency: One time, daily, weekly, or monthly (required).
• Comment: A string to be displayed in the task's property sheet in the scheduler UI (optional).

There's a little catch when creating a weekly repeating task: if you want the task to repeat on Mondays, the starting date must be a Monday. Similarly, for monthly tasks, if you want the task to run on the 20th, the starting date must be a 20th.

The CScheduledTask member functions for doing all this are listed below:

void SetProgram ( LPCTSTR szProgram )
void SetParameters ( LPCTSTR szParams )
void SetStartingDir ( LPCTSTR szDir )
void SetAccountName ( LPCTSTR szAccount )
void SetPassword ( LPCTSTR szPassword )
void SetStartDateTime ( const CTime& timeStart )
void SetStartDateTime ( const SYSTEMTIME& timeStart )
void SetEndDate ( const CTime& timeEnd )
void SetEndDate ( const SYSTEMTIME& timeEnd )
void SetFrequency ( CScheduledTask::ETaskFrequency freq )
void SetComment ( LPCTSTR szComment )

Note that there are two functions for setting the starting time, and two for the ending date. The two overloads let you pass in a CTime or SYSTEMTIME, depending on whatever format you use in your code.

ETaskFrequency is an enumeration that has the following values:

enum ETaskFrequency
    {
    freqOnce, freqDaily, freqWeekly, freqMonthly
    };

Once you've set all the relevant info, call the SaveTask() function:

HRESULT SaveTask ( LPCTSTR szTaskName, BOOL bFailIfExists = FALSE )

The return value is S_OK if the save was successful. If you call this function before setting a required parameter (i.e., task name, start date/time, or frequency), the return value is E_FAIL. If a scheduler COM method fails, the HRESULT returned is the error returned by the last COM method that was called. In the debug version, CScheduledTask will display a trace message listing which method failed.

The bFailIfExists parameter determines if SaveTask() will bail out if a task with the given name already exists. The default behavior is to replace an existing task.

Deleting a task

Deleting a task is quite easy - just call the DeleteTask function:

static HRESULT DeleteTask ( LPCTSTR szTaskName )

Note that this is a static function, and it works independently of everything else in the class. This function also returns an HRESULT, similar to SaveTask().

Other functions

If you have the need to clear out the contents of a CScheduledTask object, call the Reset function:

void Reset();

I have also included accessor functions to return the various task parameters. They are:

BOOL           GetStartDateTime ( CTime& ) const;
BOOL           GetEndDate ( CTime& ) const;
ETaskFrequency GetFrequency() const;
CString        GetProgram() const;
CString        GetParameters() const;
CString        GetStartingDir() const;
CString        GetAccountName() const;
CString        GetComment() const;

These functions are there for the sake of completeness, they were easy to write, and they also provide a starting point for future enhancements, such as the ability to enumerate through existing tasks in the scheduler.

GetStartDateTime() and GetEndDate() return a BOOL indicating if the corresponding date/time has been set. They return TRUE if the date/time is set, or FALSE if not. GetFrequency() returns the special value freqUnset if no frequency has been set. The remaining functions return an empty string if the corresponding item has not been set. Note that there is no GetPassword() function, because the Task Scheduler API doesn't provide a way to retrieve the password.

Updates

April 18, 1999: Version 1.1 has these changes:

• Fixed some compile errors when building for Unicode. Thanks to Chris Maunder for providing the fixes!
• Fixed SaveTask() to properly check for an existing task. The change was necessary because I worked around a bug in IE 4, but the bug was fixed in IE 5, resulting in my code breaking when run on IE 5.
• Added a #pragma to automatically link with mstask.lib, so you don't have to remember to do that in your app's project settings.
• Added a check after the CoCreateInstance() call to see if the error is REGDB_E_CLASSNOTREG. If so, I display a nicer trace message explaining that you don't have the scheduler installed.

November 27, 1999: Version 1.2 has these changes:

• Added functions to set an account and password for a task, so the task will run on NT.