About the Task Scheduler

The Task Scheduler allows you to perform automated tasks on a chosen machine. The Task Scheduler will monitor whatever criteria you choose and execute the task when the criteria for executing the task have been met. For example, you can have the machine run ScanDisk at 7pm every Sunday.


What is a Task?

You may be wondering what exactly a task is. A task is an object that the Task Scheduler can execute. A task can be any Win32 application, Win16 application, OS/2 application, MS-DOS application, batch file (*.BAT), command file (*.CMD) or any properly registered file type.

A task has one or more triggers that determine when the task should be executed.

You use the ITask interface to control and modify tasks.


What is a Trigger?

A trigger is a set of criteria, that when met, will activate and cause a task to be executed. There are two types of triggers, time-based and event-based.

Time based triggers will activate at a specified point in time. Not only can you can set the time that they become active, you can have them activate once, daily, weekly, monthly, on a specified day of the month (the 3rd day of the month) or on a specified day of the week of a month (the second Tuesday of the month).

Event-based triggers will activate in response to certain system events. There are event-based triggers that become active when the system starts up, when a user logs on to the local machine or when the system becomes idle. The last of these are known as Idle Triggers.

You use the ITaskTrigger interface to control and modify triggers.


All About Idle Triggers

When no keyboard or mouse input occurs, the machine is considered to be in an idle state. An idle trigger is an event-based trigger that becomes active a specified amount of time after the machine becomes idle. When you set the TASK_EVENT_TRIGGER_ON_IDLE flag for a task, you create an idle trigger. You use the ITask::SetIdleWait method to set the amount of time that the system is idle before the task is executed. You can use the ITask::GetIdleWait method to retrieve this same value.

Note: The Task Scheduler service that monitors triggers on Windows NT does not monitor idle conditions and will not activate any idle triggers. This does not, however, affect the task itself. The TASK_EVENT_TRIGGER_ON_IDLE flag can be set and the task idle time can be set and retrieved on Windows NT and all of the information will be persistent. The only difference is that, on Windows NT, the idle trigger will never be activated.


Task Names

Before getting started, we need to discuss task names. A task name is the name of the file that the task information is stored in. These files all have the .JOB extension and reside in the tasks folder. You can retrieve the location of tasks folder from the registry by getting the data for the following value:

HKEY_LOCAL_MACHINE

   SOFTWARE

      Microsoft

         SchedulingAgent

            TasksFolder

All of the Task Scheduler methods that take a task name will examine the name and add the .JOB extension if it is not already present.


The Starting Point - ISchedulingAgent

ISchedulingAgent is the starting point for programming the Task Scheduler. ISchedulingAgent allows you to enumerate, add, modify and delete tasks, and administer tasks on another computer. All you have to do to obtain the ISchedulingAgent interface is to call CoCreateInstance with the scheduling agent class identifier and interface identifier. The following example shows how this is done.

#include <mstask.h>

ISchedulingAgent  *g_pSchedulingAgent;

BOOL Initialize(void)

{

HRESULT  hr;

CoInitialize(NULL);

hr = CoCreateInstance(  CLSID_CSchedulingAgent,

                        NULL,

                        CLSCTX_INPROC_SERVER,

                        IID_ISchedulingAgent,

                        (LPVOID*)&g_pSchedulingAgent);

return SUCCEEDED(hr);

}

When you no longer need the ISchedulingAgent interface, simply call it's Release method. Don't forget that you need to call CoInitialize or OleInitialize before calling CoCreateInstance. Also make sure you call CoUninitialize or OleUninitialize when you are done using OLE.


The Target Computer

In Task Scheduler terms, the target computer is the computer to which the ISchedulingAgent object is linked. All of the tasks associated with the ISchedulingAgent object are located on the target computer. When you create a new instance of ISchedulingAgent, the local computer is the target computer by default.

You can use ISchedulingAgent to administer tasks on a remote computer. There are some rules and regulations for remote task administration:

•	You can view tasks on a remote computer running Windows NT only if you are an administrator on that remote computer.

•	You can edit tasks on a remote Windows 95 computer only if that remote computer has remote registry software installed and shares the x$ share, where x is the hard drive on which the Tasks folder resides.

You use ISchedulingAgent::SetTargetComputer to change the target computer and ISchedulingAgent::GetTargetComputer to get the name of the target computer. Computer names are always in Universal Naming Convention (UNC) format.


Enumerating Tasks

To enumerate tasks, you should call ISchedulingAgent::Enum. This will give you a IEnumTasks interface pointer that you can to retrieve the names of the tasks. Once you have the name of a task, you can call ISchedulingAgent::Activate to get the ITask interface for the task. Once you have the ITask interface pointer, you can get or set any of the task information that you want. The following example enumerates all of the tasks and adds them to a ListView control to display them.

BOOL LoadTaskList(HWND hwndListView)

{

HRESULT     hr;

IEnumTasks  *pEnum;

hr = g_pSchedulingAgent->Enum(&pEnum);

if(SUCCEEDED(hr))

   {

   LPWSTR   *ppNames;

   DWORD    dwFetched;

   while(SUCCEEDED(pEnum->Next(5, &ppNames, &dwFetched)) && dwFetched)

      {

      DWORD i;

      TCHAR szString[MAX_PATH];

      for(i = 0; i < dwFetched; i++)

         {

         if(ConvertString(szString, *(ppNames + i), sizeof(szString)))

            {

            LV_ITEM  lvItem;

            ITask *pTask;

            ZeroMemory(&lvItem, sizeof(lvItem));

            lvItem.mask = LVIF_TEXT | LVIF_IMAGE | LVIF_PARAM;

            lvItem.pszText = szString;

            lvItem.iImage = I_IMAGECALLBACK;

            lvItem.iItem = ListView_GetItemCount(hwndListView);

            //get the ITask for this task

            hr = g_pSchedulingAgent->Activate(  *(ppNames + i),

                                                IID_ITask,

                                                (LPUNKNOWN*)&pTask);

            if(SUCCEEDED(hr))

               {

               lvItem.lParam = (LPARAM)pTask;

               //add the item to the list

               ListView_InsertItem(hwndListView, &lvItem);

               }

            }

         //free the string

         CoTaskMemFree(*(ppNames + i));

         }

      //free the array

      CoTaskMemFree(ppNames);

      }

   pEnum->Release();

   return TRUE;

   }

return FALSE;

}

The task names are always given in wide characters, so you need to convert the string to ANSI characters if your application is not built for UNICODE. The ConvertString function handles this for you.

BOOL ConvertString(LPTSTR pszOut, LPWSTR pwszIn, DWORD dwSize)

{

#ifdef UNICODE

   if(lstrcpyn(pszOut, pwszIn, dwSize))

      {

      return TRUE;

      }

#else

   if(WideCharToMultiByte( CP_ACP,

                           0,

                           pwszIn,

                           -1,

                           pszOut,

                           dwSize,

                           NULL,

                           NULL))

      {

      return TRUE;

      }

#endif   //UNICODE

return FALSE;

}


Creating Tasks

Listing the current tasks is all well and good, but how do you create your own task? There are two ways to do this. The first is to use ISchedulingAgent::NewTask. This method will instantiate an ITask object and assign it the name you provide. The second is to call ISchedulingAgent::AddTask. When you take this route, it is your responsibility to instantiate the ITask object and then add the task with the name you supply.

The name you supply for the task must be unique within the tasks folder. If a task with that name already exists, ISchedulingAgent::NewTask and ISchedulingAgent::AddTask will return ERROR_FILE_EXISTS. If you get this return value, you should specify a different name and attempt to add the task again.


Deleting Tasks

You use the ISchedulingAgent::Delete method to delete a task. You simply supply the name of the task and, if the task is present, it will be deleted.


Manipulating Tasks - ITask

ITask is the interface that you use to control a task object. You can set and retrieve all of the task's information, execute and terminate the task, add and delete triggers, and even allow the user to modify the task with a standard user interface.

ITask implements all of the methods necessary to set and retrieve all of the task's information. Take a look at the ITask references for a complete list of the methods for affecting the task. The method names are rather self-explanatory.


Executing and Terminating a Task

If you would like to programmatically cause a task to run, you simply call the task object's ITask::Run method. This will attempt to execute the task and will return as soon as the task has started.

If it becomes necessary for you to terminate a running task, you can use ITask::Terminate. This method will attempt to terminate the task and return a success/failure code, informing your application if it was successful or not. Terminate will attempt to gracefully shut down the application by sending it a WM_CLOSE message. It will then wait approximately three minutes for the process to terminate. If the process has not terminated within that three minutes, Terminate will use TerminateProcess to terminate the task. As you can see, there is potential here for data loss if the application must be terminated the hard way. Therefore, you should avoid terminating tasks if at all possible.


Creating and Deleting Triggers

When you use ITask::CreateTrigger, you are creating a brand new ITaskTrigger object. ITask::CreateTrigger gives you both the new trigger's numeric index and the ITaskTrigger interface pointer. You can then use this interface to modify the trigger parameters. By the same token, ITask::DeleteTrigger will delete the trigger that has the numeric index specified.


Editing a Task

When you are viewing the Tasks folder in Explorer, you can edit the task by double-clicking on it. When you do this, the Scheduling Agent actually call's the tasks object's ITask::EditTask method. Fortunately, this method has been exposed so that you can do the same thing programmatically without having to implement all of the user interface code and resources. The only thing you have to provide is a parent window handle.


Manipulating Triggers - ITaskTrigger

The ITaskTrigger interface allows you to modify an existing trigger's parameters, but how do you get the ITaskTrigger interface for a trigger object? There are two ways to do this. The first is to create a new trigger using ITask::CreateTrigger and the second is to use ITask::GetTrigger. The latter method takes the desired trigger's numerical index.

Once you have the interface, you can use ITaskTrigger::SetTrigger to set the trigger information and ITaskTrigger::GetTrigger to get the trigger object's information. ITaskTrigger::GetTriggerString will give you a formatted string describing the trigger. You can use this string to display information about the trigger.


Task Scheduler References

The following programming elements are used and/or implemented by the task scheduler.

Interfaces

IEnumTasks

ISchedulingAgent

ITask

ITaskTrigger

Structures, Constants and Enumerations

DAILY

MONTHLYDATE

MONTHLYDOW

TASK_TRIGGER

TASK_TRIGGER_TYPE

TRIGGER_TYPE_UNION

WEEKLY


ITaskTrigger Interface Method Groups

Applications use the methods of the ITaskTrigger interface to access and set triggers for a task. Triggers specify task start times, repetition criteria, and other parameters. The methods are organized into the following groups.

IUnknown Methods 	Description

QueryInterface 	Requests an interface pointer from the object.

AddRef 	Increments the object's reference count.

Release 	Decrements the object's reference count.

ITaskTrigger Methods

SetTrigger

GetTrigger

GetTriggerString


ITaskTrigger::SetTrigger

HRESULT SetTrigger(

   const PTASK_TRIGGER pTrigger);

Sets the task trigger values.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pTrigger

Address of a TASK_TRIGGER structure containing the values that define the new task trigger.


ITaskTrigger::GetTrigger

HRESULT GetTrigger(

   PTASK_TRIGGER pTrigger);

Retrieves the current task trigger.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pTrigger

Address of a TASK_TRIGGER structure that will contain the current task trigger. You must set the cbTriggerSize member of pTrigger to sizeof(TASK_TRIGGER) before passing it to this method.


ITaskTrigger::GetTriggerString

HRESULT GetTriggerString(

   LPWSTR * ppwszTrigger);

Retrieves the current task trigger in the form of a string. This string appears in the Scheduling Agent user interface in a form similar to "At 2PM every day, starting 5/11/96."

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszTrigger

Address of an LPWSTR that will contain the description of the current task trigger. The caller must free this string using the CoTaskMemFree function.


ITask Interface Method Groups

Applications use the methods of the ITask interface to set and retrieve task information and to run and terminate tasks. The methods are organized into the following groups.

IUnknown Methods 	Description

QueryInterface 	Requests an interface pointer from the object.

AddRef 	Increments the object's reference count.

Release 	Decrements the object's reference count.

ITask Methods

Run

Terminate

EditTask

CreateTrigger

DeleteTrigger

GetTriggerCount

GetTrigger

GetTriggerString

GetRunTimes

SetApplicationName

GetApplicationName

SetParameters

GetParameters

SetWorkingDirectory

GetWorkingDirectory

SetAccountInformation

GetAccountInformation

SetComment

GetComment

SetPriority

GetPriority

SetMaxRunTime

GetMaxRunTime

SetIdleWait

GetIdleWait

SetErrorRetryCount

GetErrorRetryCount

SetErrorRetryInterval

GetErrorRetryInterval

SetFlags

GetFlags

SetTaskData

GetTaskData

GetMostRecentRunTime

GetNextRunTime

GetExitCode

GetStatus

SetCreator

GetCreator


ITask::Run

HRESULT Run(void);

Starts the task immediately.

•	Returns one of the following values:

S_OK 	The task was successfully started.

SCHED_E_TASK_NOT_READY 	The task object has no associated application name.

E_INVALIDARG 	The task object is not persistent.

E_OUTOFMEMORY 	Not enough memory is available to start the task.


ITask::Terminate

HRESULT Terminate(void);

Terminates the execution of the task, if it is running.

•	Returns one of the following values:

S_OK 	The task was successfully terminated.

SCHED_E_TASK_NOT_RUNNING 	The task has no running instances.

E_OUTOFMEMORY 	Not enough memory is available to terminate the task.

After calling ITask::Terminate, the Scheduling Agent first sends a WM_CLOSE message to the associated application. If the application has not exited within three minutes, then TerminateProcess is invoked. If more than one instance of a task is running, all instances are terminated. In Microsoft® Windows NT®, you should select the "Allow Service to Interact with Desktop" check box in the Startup dialog box of the Services control panel. If you do not, the task windows will not be visible to the Scheduling Agent and it will always call TerminateProcess instead of sending a WM_CLOSE message.


ITask::EditTask

HRESULT EditTask(

   HWND hParent,

   BOOL fReserved);

Opens the configuration properties for the task.

•	Returns S_OK if successful, STG_E_NOTFILEBASEDSTORAGE if the task object is not persistent, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

hParent

Handle to the parent window of the configuration properties window.

fReserved

Reserved for internal use; this must be zero.

When you open the Properties for a task from Windows, the task scheduler calls this method to display the task's properties.


ITask::CreateTrigger

HRESULT CreateTrigger(

   WORD * piNewTrigger,

   ITaskTrigger ** ppTrigger);

Creates a new task trigger and adds it to the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

piNewTrigger

Address of a value that will contain the new trigger's index.

ppTrigger

Address of a pointer to an ITaskTrigger interface that will contain the new trigger.


ITask::DeleteTrigger

HRESULT DeleteTrigger(

   WORD iTrigger);

Deletes a task trigger.

•	Returns S_OK if successful, or SCHED_E_TRIGGER_NOT_FOUND if the specified trigger is invalid.

iTrigger

Index of the trigger to delete.


ITask::GetTriggerCount

HRESULT GetTriggerCount(

   WORD * pwCount);

Retrieves the total number of triggers for the current task.

•	Returns S_OK if successful, or E_INVALIDARG if the argument is not valid.

pwCount

Address of a value that will contain the number of triggers for the current task.


ITask::GetTrigger

HRESULT GetTrigger(

   WORD iTrigger,

   ITaskTrigger ** ppTrigger);

Retrieves a task trigger.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

iTrigger

Value that specifies the index of the trigger to retrieve.

ppTrigger

Address of a pointer to an ITaskTrigger interface that will contain the retrieved task trigger.


ITask::GetTriggerString

HRESULT GetTriggerString(

   WORD iTrigger,

   LPWSTR * ppwszTrigger);

Retrieves the current task trigger in the form of a string. This string appears in the Scheduling Agent user interface in a form similar to "At 2PM every day, starting 5/11/96."

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

iTrigger

Index of the trigger to retrieve.

ppwszTrigger

Address of an LPWSTR that will contain the description of the task trigger specified in iTrigger. The caller must free this string using the CoTaskMemFree function.


ITask::GetRunTimes

HRESULT GetRunTimes(

   const LPSYSTEMTIME pstBegin,

   const LPSYSTEMTIME pstEnd,

   WORD * pCount,

   LPSYSTEMTIME * rgstTaskTimes);

Retrieves the time-based task run times for a specified time period.

•	Returns one of the following values:

S_OK 	The requested number of run times was retrieved.

S_FALSE 	GetRunTimes succeeded, but fewer than the requested number of run times was retrieved. The number of run times retrieved is contained in the value pointed to by pCount. If the number of run times retrieved is zero, there are also no event-based triggers that can cause the task to be executed during the specified time period.

SCHED_S_EVENT_TRIGGER 	No run times exist for the specified time period, but event-based triggers exist that may cause the task to run during the specified time period.

SCHED_S_TASK_NO_VALID_TRIGGERS 	The task is enabled but has no valid triggers.

SCHED_S_TASK_DISABLED 	The task is disabled.

E_INVALIDARG 	One or more of the arguments are invalid.

E_OUTOFMEMORY 	There is insufficient memory to compute the result.

pstBegin

Address of a SYSTEMTIME structure that contains the starting time of the time period to check. This value is inclusive.

pstEnd

Address of a SYSTEMTIME structure that contains the ending time of the time period to check. This value is exclusive. If NULL is passed for this value, then the end time is infinite.

pCount

Address of a value that specifies the number of run times to retrieve. Before calling GetRunTimes, this value contains the number of run times being requested. This can be a number between 1 and TASK_MAX_RUN_TIMES. After GetRunTimes is called, this value contains the number of run times actually retrieved.

rgstTaskTimes

Address of a pointer to an array of SYSTEMTIME structures. This array will contain pCount run times. The pointer must be freed using the CoTaskMemFree function.


ITask::SetApplicationName

HRESULT SetApplicationName(

   LPCWSTR pwszApplicationName);

Assigns a specific application to the current task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszApplicationName

LPCWSTR that contains an application's name. To clear the application name, set pwszApplicationName to L"".

If you do not specify a path for the application, then the scheduler will search the environment path to find the correct path. If the application name specifies a program, it should use the .exe extension to ensure that the Scheduling Agent user interface properly displays the application's icon.


ITask::GetApplicationName

HRESULT GetApplicationName(

   LPWSTR * ppwszApplicationName);

Retrieves the name of the application that the task is associated with.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszApplicationName

Address of an LPWSTR that will contain the name of the application the current task is associated with. The caller must free this string using the CoTaskMemFree function.


ITask::SetParameters

HRESULT SetParameters(

   LPCWSTR pwszParameters);

Sets the command-line parameters for the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszParameters

LPCWSTR that contains task parameters. These parameters are passed as command lines to the application the task will run.

If the ApplicationName property contains a document to run by association, then the Parameters property is ignored. To clear the parameters, set pwszParameters to L"".


ITask::GetParameters

HRESULT GetParameters(

   LPWSTR * ppwszParameters);

Retrieves the task's command-line parameters.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszParameters

Address of an LPWSTR that will contain the current task's parameters. The caller must free this string using the CoTaskMemFree function.


ITask::SetIdleWait

HRESULT SetIdleWait(

   WORD wMinutes);

Sets the idle wait time for the task.

•	Returns S_OK.

wMinutes

Value of the task's idle wait time, in minutes.

If the task has the TASK_EVENT_TRIGGER_ON_IDLE flag set, the task will run when wMinutes have elapsed since the most recent keyboard or mouse event. If the TASK_FLAG_START_ONLY_IF_IDLE flag is set, the task will run only if the assigned starting time is at least wMinutes after the most recent keyboard or mouse event.


ITask::GetIdleWait

HRESULT GetIdleWait(

   WORD * pwMinutes);

Retrieves the task's idle wait time.

•	Returns S_OK if successful, or E_INVALIDARG if the argument is not valid.

pwMinutes

Address of a value that will contain the current task's idle wait time.

If the task has the TASK_EVENT_TRIGGER_ON_IDLE flag set, the task will run when pwMinutes have elapsed since the most recent keyboard or mouse event. If the TASK_FLAG_START_ONLY_IF_IDLE flag is set, the task will run only if the assigned starting time is at least pwMinutes after the most recent keyboard or mouse event.


ITask::SetCreator

HRESULT SetCreator(

   LPCWSTR pwszCreator);

Sets the task's creator.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszCreator

LPCWSTR that contains the task's creator.


ITask::GetCreator

HRESULT GetCreator(

   LPWSTR * ppwszCreator);

Retrieves the task's creator.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszCreator

Address of an LPWSTR that will contain the current task's creator. The caller must free this string using the CoTaskMemFree function.


ITask::SetWorkingDirectory

HRESULT SetWorkingDirectory(

   LPCWSTR pwszWorkingDirectory);

Sets the working directory for the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszWorkingDirectory

LPCWSTR that contains a directory path. The application will start with this directory as the current working directory. To clear the directory, set pwszWorkingDirectory to L"".


ITask::GetWorkingDirectory

HRESULT GetWorkingDirectory(

   LPWSTR * ppwszWorkingDirectory);

Retrieves the task's working directory.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszWorkingDirectory

Address of an LPWSTR that will contain the task's working directory. The caller must free this string using the CoTaskMemFree function.


ITask::SetAccountInformation

HRESULT SetAccountInformation(

   LPCWSTR pwszAccountName,

   LPCWSTR pwszPassword);

Sets the account name and password for the task. This method is for Windows NT; it does nothing in Windows 95®.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszAccountName

LPCWSTR that contains the account name. This account is assigned to the current task..

pwszPassword

LPCWSTR that contains the account password. This password is assigned to the current task.


ITask::GetAccountInformation

HRESULT GetAccountInformation(

   LPWSTR * ppwszAccountName);

Retrieves the account name for the task. This method is for Windows NT; it does nothing in Windows 95.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszAccountName

Address of an LPWSTR that will contain the account name for the current task.

The caller must free the string using the CoTaskMemFree function.


ITask::SetComment

HRESULT SetComment(

   LPCWSTR pwszComment);

Sets the comment for the task. The comment, which appears in the Properties window, provides additional information about the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszComment

LPCWSTR that contains a comment.

To clear the comment, set pwszComment to L"".


ITask::GetComment

HRESULT GetComment(

   LPWSTR * ppwszComment);

Retrieves the comment for the task. The comment, which appears in the Properties window, provides additional information about the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszComment

Address of an LPWSTR that will contain the comment for the current task. The caller must free this string using the CoTaskMemFree function.


ITask::SetPriority

HRESULT SetPriority(

   DWORD dwPriority);

Sets the priority for the task.

•	Returns S_OK if successful, or E_INVALIDARG if the argument is not valid.

dwPriority

Value assigned as the priority for the current task. The priority value determines the frequency and length of a process' time slices. This applies only to Windows NT and has no effect in Windows 95. It is taken from the CreateProcess priority class and can be one of following flags (in descending order of thread scheduling priority).

REALTIME_PRIORITY_CLASS

HIGH_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS

IDLE_PRIORITY_CLASS


ITask::GetPriority

HRESULT GetPriority(

   DWORD * pdwPriority);

Retrieves the priority for the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pdwPriority

Address of a DWORD that will contain the priority for the current task. The priority value determines the frequency and length of a process' time slices. This applies only to Windows NT and has no effect in Windows 95. It is taken from the CreateProcess priority class and can be one of the following flags (in descending order of thread scheduling priority).

REALTIME_PRIORITY_CLASS

HIGH_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS

IDLE_PRIORITY_CLASS


ITask::SetMaxRunTime

HRESULT SetMaxRunTime(

   DWORD dwMaxRunTime);

Sets the maximum time the task can run before terminating.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

dwMaxRunTime

Value assigned as the maximum run time for the current task, in milliseconds.

If the maximum run time is reached during the execution of a task, the Scheduling Agent first sends a WM_CLOSE message to the associated application. If the application has not exited within three minutes, then TerminateProcess is invoked.


ITask::GetMaxRunTime

HRESULT GetMaxRunTime(

   DWORD * pdwMaxRunTime);

Retrieves the maximum time the task can run before terminating, in milliseconds.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pdwMaxRunTime

Address of a value that will contain the maximum run time of the current task.

If the maximum run time is reached during the execution of a task, the Scheduling Agent first sends a WM_CLOSE message to the associated application. If the application hasn't exited within three minutes, then TerminateProcess is invoked.


ITask::SetErrorRetryCount

HRESULT SetErrorRetryCount(

   WORD wRetryCount);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

wRetryCount

Value assigned as the number of error retries for the current task.


ITask::GetErrorRetryCount

HRESULT GetErrorRetryCount(

   WORD * pwRetryCount);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwRetryCount

Address of a value that will contain the number of error retries for the current task.


ITask::SetErrorRetryInterval

HRESULT SetErrorRetryInterval(

   WORD wRetryInterval);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

wRetryInterval

Value assigned as the interval between error retries for the current task.


ITask::GetErrorRetryInterval

HRESULT GetErrorRetryInterval(

   WORD * pwRetryInterval);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwRetryInterval

Address of a value that will contain the time interval between retries of the current task after an error occurs.


ITask::SetFlags

HRESULT SetFlags(

   DWORD dwFlags);

Sets the flags that modify the task's behavior.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

dwFlags

Value that contains a combination of one or more of the following flags.

TASK_FLAG_INTERACTIVE

The task will not be displayed in the Tasks folder and no user interface associated with the task will be presented to the user when the task is executed.

TASK_FLAG_DELETE_WHEN_DONE

The task will be deleted when there are no more scheduled run times.

TASK_FLAG_DISABLED

The task is disabled. This is useful to temporarily prevent a task from running at the scheduled time(s).

TASK_FLAG_HALT_ON_ERROR

The task will stop and the associated application will quit if the task encounters an error. This option is used for task queues, and is not currently implemented.

TASK_FLAG_HIDDEN

The task file is hidden. When the task begins execution, it will run in a hidden window.

TASK_FLAG_START_ONLY_IF_IDLE

The task will begin only if the computer is not in use at the scheduled start time. Windows 95 only.

TASK_FLAG_KILL_ON_IDLE_END

The task will terminate if the computer makes an idle to non-idle transition while the task is running. The computer is not considered idle until the IdleWait time elapses with no user input. Windows 95 only.

TASK_FLAG_DONT_START_IF_ON_BATTERIES

The task will not start if its target computer is running on battery power. Windows 95 only.

TASK_FLAG_KILL_IF_GOING_ON_BATTERIES

The task will end and the associated application will quit if the task's target computer switches to battery power. Windows 95 only.

TASK_FLAG_RUN_IF_CONNECTED_TO_INTERNET

Not yet implemented.


ITask::GetFlags

HRESULT GetFlags(

   DWORD * pdwFlags);

Returns the flags that modify the task's behavior.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pdwFlags

Address of a value that will contain the description of how the task behaves. See ITask::SetFlags for a list of the flags.


ITask::SetTaskData

HRESULT SetTaskData(

   WORD cBytes,

   BYTE rgbData[]);

Stores application-defined data associated with the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

cBytes

Number of bytes in the data buffer. The caller allocates and frees this memory.

rgbData

Data to copy.


ITask::GetTaskData

HRESULT GetTaskData(

   WORD * pcBytes,

   BYTE ** ppBytes);

Retrieves application-defined data associated with the task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pcBytes

Number of bytes copied.

ppBytes

Address of a BYTE pointer that will contain user-defined data for the current task. The caller must free this memory by using CoTaskMemFree.


ITask::GetMostRecentRunTime

HRESULT GetMostRecentRunTime(

   SYSTEMTIME * pstLastRun);

Retrieves the most recent time the task began running.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, SCHED_S_TASK_HAS_NOT_RUN if the task has never run, or E_OUTOFMEMORY if not enough memory is available.

pstLastRun

Address of a SYSTEMTIME structure that will contain the most recent time the current task ran.


ITask::GetNextRunTime

HRESULT GetNextRunTime(

   SYSTEMTIME * pstNextRun);

Retrieves the next time the task will run.

•	Returns an HRESULT that can be one of the following values.

S_OK

Assigns the next task time to the pstNextRun parameter.

S_FALSE

There are no more scheduled run times.

SCHED_S_EVENT_TRIGGER

There are no time triggers, only event triggers.

SCHED_S_NO_VALID_TRIGGERS

Either there are no valid triggers, or the triggers are disabled.

HRESULT

There was an error; the returned value is the failure code.

pstNextRun

Address of a SYSTEMTIME structure that will contain the next run time. The next run time is referenced from the computer's current time.


ITask::GetExitCode

HRESULT GetExitCode(

   HRESULT * pExitCode);

Retrieves the exit code for the task's associated application from the most recent time the task ran.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pExitCode

Address of a value that will contain the exit code for the task's associated application, from the most recent time the task ran.


ITask::GetStatus

HRESULT GetStatus(

   HRESULT * pStatus);

Retrieves an HRESULT that represents the task's status.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pStatus

Address of an HRESULT value that will contain the status of the current task. The status and other properties of the task are a "snapshot" and can become stale. This value is likely to be one of the following:

SCHED_S_TASK_READY 	The task is ready to run at its next scheduled time.

SCHED_S_TASK_RUNNING 	The task is currently running.

SCHED_S_TASK_DISABLED 	The task has been disabled, so it will not run at the scheduled times.

SCHED_S_TASK_NO_MORE_RUNS 	There are no more run times scheduled for this task.

SCHED_S_TASK_NOT_SCHEDULED 	One or more of the properties that are needed to run this task on a schedule are not set.

SCHED_S_TASK_NO_VALID_TRIGGERS 	The task has no triggers or the existing triggers are disabled or not set.


IEnumTasks Interface Method Groups

Applications use the methods of the IEnumTasks interface to enumerate tasks. The methods can be organized into the following groups.

IUnknown Methods 	Description

QueryInterface 	Requests an interface pointer from the object.

AddRef 	Increments the object's reference count.

Release 	Decrements the object's reference count.

IEnumTasks Methods

Next

Skip

Reset

Clone


IEnumTasks::Next

HRESULT Next(

   ULONG celt,

   LPWSTR ** rgpwszNames,

   ULONG * pceltFetched);

Retrieves the next celt tasks in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, the remaining elements are retrieved.

•	Returns S_OK if the number of tasks retrieved equals the number requested, S_FALSE if the number returned is less than the number requested (thus, there are no more tasks to enumerate), E_INVALIDARG if any parameter is invalid, and E_OUTOFMEMORY if not enough memory is available.

celt

Number of tasks to retrieve.

rgpwszNames

Address of an array of pointers to character strings that will contain the file names of the tasks returned from the enumeration sequence. These file names are taken from the "Tasks" folder and have the .job extension. You must free each LPWSTR in the array and the array itself using CoTaskMemFree.

pceltFetched

Address of a value that will contain the number of tasks returned in rgpwszNames. If the celt parameter is 1, this parameter can be NULL.


IEnumTasks::Skip

HRESULT Skip(

   ULONG celt);

Skips the next celt number of tasks in the enumeration sequence.

•	S_OK if the number of elements skipped equals celt, S_FALSE if the number of elements remaining in the sequence is less than celt, and E_INVALIDARG if celt is less than or equal to zero.

celt

Number of tasks to be skipped.


IEnumTasks::Reset

HRESULT Reset(void);

Resets the enumeration sequence to the beginning.

•	Returns S_OK, or E_OUTOFMEMORY if there is not enough available memory.

A call to this method does not guarantee that the same set of tasks will be enumerated after the reset, because it depends on the collection being enumerated.


IEnumTasks::Clone

HRESULT Clone(

   IEnumTasks ** ppEnumTasks);

Creates another enumerator that contains the same enumeration state as the current one. Using this method, a client can record a particular point in the enumeration sequence and return to that point later. The new enumerator supports the same interface as the original.

•	Returns S_OK if successful; E_INVALIDARG the argument is not valid, E_OUTOFMEMORY if there is not enough memory available, or E_UNEXPECTED if an error occurs.

ppEnumTasks

Address of a pointer to an IEnumTasks interface that will be assigned to the newly created enumeration. If the method fails, this parameter will be undefined.


ISchedulingAgent Interface Method Groups

Applications use the methods of the ISchedulingAgent interface to schedule tasks and set up task queues. The methods can be organized into the following groups.

IUnknown Methods 	Description

QueryInterface 	Requests an interface pointer from the object.

AddRef 	Increments the object's reference count.

Release 	Decrements the object's reference count.

ISchedulingAgent Methods

SetTargetComputer

GetTargetComputer

Enum

Activate

Delete

NewTask

AddTask

NewQueue

AddQueue

IsTask

IsQueue


ISchedulingAgent::SetTargetComputer

HRESULT SetTargetComputer(

   LPCWSTR pwszComputer);

Selects the computer that the ISchedulingAgent interface operates on. This allows remote task management and enumeration. The user must have administrative access on the remote computer to use this method. For more information on remote installation requirements, refer to mstask.hlp.

•	Returns one of the following values:

S_OK 	The method was successful.

SCHED_E_SERVICE_NOT_INSTALLED 	The Task Scheduler Service is not installed on the target computer.

E_INVALIDARG 	pwszComputer is not valid.

E_OUTOFMEMORY 	A memory allocation failure occurred.

pwszComputer

LPCWSTR that specifies the target computer for the current task. The machine name must include two leading backslashes. To indicate that the local machine is the target computer, set this value to NULL or to the local machine's universal naming convention (UNC) name.


ISchedulingAgent::GetTargetComputer

HRESULT GetTargetComputer(

   LPWSTR * ppwszComputer);

Retrieves the task's target computer. For more information on remote installation requirements, refer to mstask.hlp.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppwszComputer

Address of an LPWSTR that will contain the name of the target computer for the current task. This string is allocated by the callee and freed by the caller using CoTaskMemFree.


ISchedulingAgent::Enum

HRESULT Enum(

   IEnumTasks ** ppEnumTasks);

Retrieves a pointer to an OLE enumerator object that will enumerate the tasks in the current task folder. The current folder resides on the computer returned by ISchedulingAgent::GetTargetComputer, which defaults to the local machine if not previously set by a call to ISchedulingAgent::SetTargetComputer.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

ppEnumTasks

Address of a pointer to an IEnumTasks interface. This interface will contain the enumeration context of the current task(s).


ISchedulingAgent::Activate

HRESULT Activate(

   LPCWSTR pwszName,

   REFIID riid,

   IUnknown ** ppunk);

Returns an active interface to the specified task.

•	Returns one of the following values:

S_OK 	The method was successful.

SCHED_E_UNKNOWN_OBJECT_VERSION 	The task object version is either unsupported or invalid.

E_INVALIDARG 	pwszName is not valid.

E_OUTOFMEMORY 	A memory allocation failure occurred.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszName

LPCWSTR that specifies the name of the task to activate.

riid

Reference identifier of the interface being requested.

ppunk

Address of an interface pointer that will receive the requested interface.


ISchedulingAgent::Delete

HRESULT Delete(

   LPCWSTR pwszName);

Deletes a task.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszName

LPCWSTR that specifies the name of the task to delete.


ISchedulingAgent::NewTask

HRESULT NewTask(

   LPCWSTR pwszTaskName,

   REFIID riid,

   IUnknown ** ppunk);

Allocates space for a new task and retrieves its address. Unlike ISchedulingAgent::AddTask, this function handles memory allocation automatically.

•	Returns one of the following values:

S_OK 	The operation was successful.

ERROR_FILE_EXISTS 	A task with the specified name already exists.

E_INVALIDARG 	One or more of the arguments are not valid.

E_OUTOFMEMORY 	Not enough memory is available to complete the operation.

pwszTaskName

LPCWSTR that specifies the new task's name. The task name must conform to Windows NT file-naming conventions but cannot include backslashes, because nesting within the task folder object is not allowed.

riid

Reference identifier of the interface being requested.

ppunk

Address of an interface pointer that will receive the requested interface.


ISchedulingAgent::AddTask

HRESULT AddTask(

   LPCWSTR pwszTaskName,

   ITask * pTask);

Adds a task to the schedule of tasks. Unlike ISchedulingAgent::NewTask, this function requires that you first allocate space for the task and pass its address in the pTask parameter.

•	Returns one of the following values:

S_OK 	The operation was successful.

ERROR_FILE_EXISTS 	A task with the specified name already exists.

E_INVALIDARG 	One or more of the arguments are not valid.

E_OUTOFMEMORY 	Not enough memory is available to complete the operation.

pwszTaskName

LPCWSTR that specifies the name of the task to add. The task name must conform to Windows NT file-naming conventions but cannot include backslashes, because nesting within the task folder object is not allowed.

pTask

Address of an ITask interface that specifies which task to add.


ISchedulingAgent::NewQueue

HRESULT NewQueue(

   LPCWSTR pwszQueueName,

   REFIID riid,

   IUnknown ** ppunk);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszQueueName

Character string that contains the name of the queue to create.

riid

Reference identifier of the interface being requested.

ppunk

Address of an interface pointer that will receive the requested interface.


ISchedulingAgent::AddQueue

HRESULT AddQueue(

   LPCWSTR pwszQueueName,

   IUnknown * pUnk);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszQueueName

Character string that specifies the name of the task queue to add.

pUnk

Address of an IUnknown interface that specifies the task queue to add.


ISchedulingAgent::IsTask

HRESULT IsTask(

   LPCWSTR pwszName);

Not currently implemented.

•	Returns S_OK if pwszName is a task; S_FALSE otherwise.

pwszName

LPCWSTR that specifies the name of the object to check.


ISchedulingAgent::IsQueue

HRESULT IsQueue(

   LPCWSTR pwszName);

Not currently implemented.

•	Returns S_OK if successful, E_INVALIDARG if the arguments are not valid, or E_OUTOFMEMORY if not enough memory is available.

pwszName

LPCWSTR that specifies the name of the object to check.


DAILY

typedef struct _DAILY {

    WORD DaysInterval;

} DAILY;

This structure defines the interval, in days, between invocations of a task. The TRIGGER_TYPE_UNION union uses an instance of this structure as part of the TASK_TRIGGER structure definition.

DaysInterval

Number of days between invocations of a task.


WEEKLY

typedef struct _WEEKLY {

    WORD WeeksInterval;

    WORD rgfDaysOfTheWeek;

} WEEKLY;

This structure defines the interval, in weeks, between invocations of a task. The TRIGGER_TYPE_UNION union uses an instance of this structure as part of the TASK_TRIGGER structure definition.

WeeksInterval

Number of weeks between invocations of a task.

rgfDaysOfTheWeek

Value that describes the days of the week the task runs. This value is a bit field and is a combination of the following flags:

TASK_SUNDAY

The task will run on Sunday.

TASK_MONDAY

The task will run on Monday.

TASK_TUESDAY

The task will run on Tuesday.

TASK_WEDNESDAY

The task will run on Wednesday.

TASK_THURSDAY

The task will run on Thursday.

TASK_FRIDAY

The task will run on Friday.

TASK_SATURDAY

The task will run on Saturday.

The following code fragment provides an example of how you can combine these flags. This example would run a task on every other Sunday, Wednesday, and Friday:

WEEKLY example;

example.WeeksInterval = 2;

example.rgfDaysOfTheWeek = TASK_SUNDAY | TASK_WEDNESDAY | TASK_FRIDAY;


MONTHLYDATE

typedef struct _MONTHLYDATE {

    DWORD rgfDays;

    WORD rgfMonths;

} MONTHLYDATE;

This structure defines the day of the month the task will run. The TRIGGER_TYPE_UNION union uses an instance of this structure as part of the TASK_TRIGGER structure definition.

rgfDays

Value that describes the day of the month a task runs. This value is a bit field that specifies the day(s) the task will run. Bit zero corresponds to the first of the month, bit one to the second, and so forth.

rgfMonths

Value that describes the month(s) when the task runs. This value is a combination of the following flags:

TASK_JANUARY

The task will run in January.

TASK_FEBRUARY

The task will run in February.

TASK_MARCH

The task will run in March.

TASK_APRIL

The task will run in April.

TASK_MAY

The task will run in May.

TASK_JUNE

The task will run in June.

TASK_JULY

The task will run in July.

TASK_AUGUST

The task will run in August.

TASK_SEPTEMBER

The task will run in September.

TASK_OCTOBER

The task will run in October.

TASK_NOVEMBER

The task will run in November.

TASK_DECEMBER

The task will run in December.

The following code fragment provides an example of how you can combine these flags. This example would run a task quarterly:

MONTHLYDATE example;

example.rgfDays = 1;

example.rgfMonths = TASK_JANUARY | TASK_APRIL | TASK_JULY | TASK_OCTOBER;


MONTHLYDOW

typedef struct _MONTHLYDOW {

    WORD wWhichWeek;

    WORD rgfDaysOfTheWeek;

    WORD rgfMonths;

} MONTHLYDOW;

This structure (MONTHLY Day Of the Week) defines the date(s) that the task runs by month, week, and day of week. The TRIGGER_TYPE_UNION union uses an instance of this structure as part of the TASK_TRIGGER structure definition.

wWhichWeek

Value that describes the week of the month when the task runs. This value is exclusive and is one of the following flags:

TASK_FIRST_WEEK

The task will run during the first week of the month.

TASK_SECOND_WEEK

The task will run during the second week of the month.

TASK_THIRD_WEEK

The task will run during the third week of the month.

TASK_FOURTH_WEEK

The task will run during the fourth week of the month.

TASK_LAST_WEEK

The task will run during the last week of the month.

rgfDaysOfTheWeek

Value that describes the day(s) of the week specified in wWhichWeek when the task runs. This value is a combination of the following flags:

TASK_SUNDAY

The task will run on Sunday.

TASK_MONDAY

The task will run on Monday.

TASK_TUESDAY

The task will run on Tuesday.

TASK_WEDNESDAY

The task will run on Wednesday.

TASK_THURSDAY

The task will run on Thursday.

TASK_FRIDAY

The task will run on Friday.

TASK_SATURDAY

The task will run on Saturday.

rgfMonths

Value that describes the month(s) when the task runs. This value is a combination of the following flags:

TASK_JANUARY

The task will run in January.

TASK_FEBRUARY

The task will run in February.

TASK_MARCH

The task will run in March.

TASK_APRIL

The task will run in April.

TASK_MAY

The task will run in May.

TASK_JUNE

The task will run in June.

TASK_JULY

The task will run in July.

TASK_AUGUST

The task will run in August.

TASK_SEPTEMBER

The task will run in September.

TASK_OCTOBER

The task will run in October.

TASK_NOVEMBER

The task will run in November.

TASK_DECEMBER

The task will run in December.

The following code fragment provides an example of how you can combine these flags. This example would run a task on Monday and Friday of the third week of every third month:

MONTHLYDOW example;

example.wWhichWeek = TASK_THIRD_WEEK;

example.rgfDaysOfTheWeek = TASK_FRIDAY | TASK_MONDAY;

example.rgfMonths = TASK_JANUARY | TASK_APRIL | TASK_JULY | TASK_OCTOBER;


TASK_TRIGGER

typedef struct _TASK_TRIGGER {

    WORD cbTriggerSize;

    WORD Reserved1;

    WORD wBeginYear;

    WORD wBeginMonth;

    WORD wBeginDay;

    WORD wEndYear;

    WORD wEndMonth;

    WORD wEndDay;

    WORD wStartHour;

    WORD wStartMinute;

    DWORD MinutesDuration;

    DWORD MinutesInterval;

    DWORD rgFlags;

    TASK_TRIGGER_TYPE TriggerType;

    TRIGGER_TYPE_UNION Type;

    WORD Reserved2;

    WORD wRandomMinutesInterval;

} TASK_TRIGGER, * PTASK_TRIGGER;

Defines the start time, end time, duration, and modification flags for a task.

cbTriggerSize

Size of this structure, in bytes (sizeof(TASK_TRIGGER))

Reserved1

For internal use only; this value must be zero.

wBeginYear

Year that the task trigger activates. This value must be four digits (1996, not 96).

wBeginMonth

Month of the year in the wBeginYear member that the task trigger activates.

wBeginDay

Day of the month in the wBeginMonth member that the task trigger activates.

wEndYear

Year that the task trigger deactivates. This value must be four digits (1996, not 96).

wEndMonth

Month of the year in the wEndYear member that the task trigger deactivates.

wEndDay

Day of the month in the wEndMonth member that the task trigger deactivates.

wStartHour

Hour of the day the task runs. This value is on a 24-hour clock; hours go from 00 to 23.

wStartMinute

Minute of the hour in the wStartHour member that the task runs.

MinutesDuration

Number of minutes after the task starts that the trigger will remain active. For example, if you start a task at 8:00 A.M. and want to repeatedly start the task until 5:00 P.M., there would be 540 minutes in the duration.

MinutesInterval

Number of minutes between consecutive task executions. This number is counted from the start of the previous task. For example, to run a task every hour from 8 A.M. to 5 P.M., set this field to 60.

rgFlags

Value that describes the task trigger's behavior. This value is a combination of the following flags:

TASK_TRIGGER_FLAG_HAS_END_DATE

The trigger structure's end date is valid. If this flag is not set, the end date data is ignored and the trigger will be valid indefinitely.

TASK_TRIGGER_FLAG_KILL_AT_DURATION_END

This flag specifies that the task will be terminated at the end of the active trigger's lifetime. At the duration end, the Scheduling Agent first sends a WM_CLOSE message to the associated application. If the application hasn't exited in three minutes, then TerminateProcess runs. If more than one instance of a task is running, all instances are terminated.

TASK_TRIGGER_FLAG_DISABLED

The task trigger is inactive.

TriggerType

Value that determines the type of trigger for this task. This value is a member of the TASK_TRIGGER_TYPE enumerated type.

Type

Structure that determines the type of trigger for this task. This structure is a member of the TRIGGER_TYPE_UNION union.

Reserved2

For internal use only; this value must be zero.

wRandomMinutesInterval

Not currently used.


TRIGGER_TYPE_UNION

typedef union _TRIGGER_TYPE_UNION {

        DAILY Daily;

        WEEKLY Weekly;

        MONTHLYDATE MonthlyDate;

        MONTHLYDOW MonthlyDOW;

} TRIGGER_TYPE_UNION;

Defines the task trigger's invocation schedule. This union is part of the TASK_TRIGGER structure.

Daily

Structure that specifies the number of days between invocation of a task. This member is a DAILY structure.

Weekly

Structure that specifies the number of weeks between invocations of a task, and day(s) of the week the task will run. This member is a WEEKLY structure.

MonthlyDate

Structure that specifies the month(s) and day(s) of the month a task will run. This member is a MONTHLYDATE structure.

MonthlyDOW

Structure that specifies the day(s) of the year a task runs by month(s), week of month, and day(s) of week. This member is a MONTHLYDOW structure.


TASK_TRIGGER_TYPE

typedef enum _TASK_TRIGGER_TYPE {

    TASK_TIME_TRIGGER_ONCE = 0,

    TASK_TIME_TRIGGER_DAILY = 1,

    TASK_TIME_TRIGGER_WEEKLY = 2,

    TASK_TIME_TRIGGER_MONTHLYDATE = 3,

    TASK_TIME_TRIGGER_MONTHLYDOW = 4,

    TASK_EVENT_TRIGGER_ON_IDLE = 5,

    TASK_EVENT_TRIGGER_AT_SYSTEMSTART = 6,

    TASK_EVENT_TRIGGER_AT_LOGON = 7

} TASK_TRIGGER_TYPE, *PTASK_TRIGGER_TYPE;

Defines the type of trigger the task will use. This enumerated type is part of the TASK_TRIGGER structure. The trigger type determines when the task will run.

TASK_TIME_TRIGGER_ONCE

The trigger is set to run the task a single time.

TASK_TIME_TRIGGER_DAILY

The trigger is set to run the task on a daily interval.

TASK_TIME_TRIGGER_WEEKLY

The trigger is set to run the task on specific days of the week on a weekly interval.

TASK_TIME_TRIGGER_MONTHLYDATE

The trigger is set to run the task on a specific day(s) of the month.

TASK_TIME_TRIGGER_MONTHLYDOW

The trigger is set to run the task on specific days, week, and months.

TASK_EVENT_TRIGGER_ON_IDLE

The trigger is set to run the task when the system becomes idle (Windows 95 only).

TASK_EVENT_TRIGGER_AT_SYSTEMSTART

The trigger is set to run the task at system startup.

TASK_EVENT_TRIGGER_AT_LOGON

The trigger is set to run the task when a user logs on.


Further Reading

The descriptions for the following items are contained in the Win32 Software Development Kit (SDK).

CoCreateInstance

CoInitialize

CoTaskMemFree

CoUninitialize

CreateProcess

IUnknown

OleInitialize

OleUninitialize

SYSTEMTIME

TerminateProcess