TaskSched: Task Scheduler Sample

Click to open or copy the files for the TaskSched sample.

This sample demonstrates the scheduling agent API provided with installation of the Scheduling Agent package. The sample mimics the functionality of the AT command through the Scheduling Agent APIs, as opposed to the NetSchedule API used by AT. This sample implements only a small subset of the AT command set, but should be easily extensible.

The output of the sample program is one of four possibilities:

• The program can present a help file. This case occurs from command line arguments requesting help, or from input parameter lists that are longer than the expected range. Output is to stdout.
  
  
• The program can enumerate all task objects in the tasks folder. Output is provided to stdout, and consists of a line containing "Job: filename.job" followed by indented lines containing strings of the type "Trigger: text representation of trigger values". Empty task folders cause no output.
  
  
• The program can delete jobs from the job folder. This action will fail in a secure environment (Windows NT on an NTFS partition) if the caller does not have permissions to remove the file. Deletion of tasks is not limited to those that were created from this program. If the deletion succeeds, no output is displayed.
  
  
• The program can add a task from the command line. If the scheduling agent is to recognize the task, the filename (Jobname.job) given MUST have the extension ".job" on it. Otherwise, it will fail to be enumerated from this tool, the task scheduler, or anywhere else. In addition, that task will fail to run if ".job" is not the file extension. If the addition succeeds, no output is displayed. The task type that is created has a single trigger of type "ONCE" and is limited to running within the next 24 hours. Also, like AT, these jobs will be deleted upon completion of their run. For creation of other types of triggers, please consult the documentation for the TASK_TRIGGER structure.

SA.cpp contains all code needed to build the simple job submission tool. This sample demonstrates calls to methods of the following new interfaces:

1. ITaskScheduler
   
   
2. ITask
   
   
3. ITaskTrigger
   
   
4. IEnumWorkItems

This application is similar in functionality to the "AT" command provided with Windows NT. However, the AT command functions through the NetSchedule APIs, as opposed to the COM interfaces demonstrated here. The Task Scheduler replaces Atsvc.exe and implements those APIs as a restricted subset of the new ones demonstrated here.

On Win9x systems, the Task Scheduler replaces the System Agent, providing more flexible and reliable scheduling options than previously available. However, although the SAGE jobs are converted to Task Scheduler work items, the actual SAGE API has been abandoned and is not implemented. The Task Scheduler APIs provide a greater degree of freedom and robustness than those APIs. This code demonstrates a stripped version of AT rewritten to use the new APIs.

About Task Scheduler

Task Scheduler is a scheduling service and user interface that is available as a common resource with the Microsoft Windows® 98 operating system. Windows 98 includes Task Scheduler as a Component Object Model (COM) interface. Task Scheduler manages all aspects of job scheduling: starting jobs, enumerating currently running jobs, tracking job status, and so on. In Task Scheduler, the user works with a folder under My Computer called Scheduled Tasks, which lists currently scheduled items and enables creation of new tasks. The Task Scheduler replaces the Microsoft Windows^® 95 System Agent.

For more information, see Component Object Model.

Building SDK Samples

This sample uses the following keywords:

_getmbcp; activate; addjob; cleanup; cocreateinstance; coinitialize; converttosystemtime; cotaskmemfree; couninitialize; createtrigger; delete; deletejob; displayhelp; enum; enumeratejobs; failed; getlocaltime; gettriggercount; gettriggerstring; lstrcmpia; multibytetowidechar; newworkitem; next; queryinterface; release; save; setaccountinformation; setapplicationname; setcomment; setflags; setparameters; settrigger; switch; wcslen; wcstoul; wprintf; wscanf