
The interfaces and methods described in the following sections illustrate the necessary implementations of functionality available within the Task Scheduler. Many of these same task options are available to the user from the Scheduled Tasks user interface.
The collection of interfaces and methods available to the developer from Task Scheduler represents the programmatic techniques necessary to implement the functionality of task management.
| IEnumWorkItems |
| IProvideTaskPage |
| IScheduledWorkItem |
| ITaskScheduler |
| ITask |
| ITaskTrigger |
Applications use the methods of the IEnumWorkItems interface to enumerate tasks. The following list of methods is organized in vtable order.
| IEnumWorkItems methods | |
| Next | |
| Skip | |
| Reset | |
| Clone |
HRESULT Clone(
IEnumWorkItems ** ppEnumWorkItems
);
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.
| S_OK | The operation was successful. |
| E_INVALIDARG | The argument is not valid. |
| E_OUTOFMEMORY | There is not enough memory available. |
| E_UNEXPECTED | An error occurred. |
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.
| S_OK | The number of tasks retrieved equals the number requested. |
| S_FALSE | The number returned is less than the number requested (thus there are no more tasks to enumerate). |
| E_INVALIDARG | A parameter is invalid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT Reset(void);
Resets the enumeration sequence to the beginning.
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.
HRESULT Skip(
ULONG celt
);
Skips the next celt number of tasks in the enumeration sequence.
| S_OK | The number of elements skipped equals celt. |
| S_FALSE | The number of elements remaining in the sequence is less than celt. |
| E_INVALIDARG | celt is less than or equal to zero. |
Applications use the method of the IProvideTaskPage interface to have access to the task object's property sheet settings.
| IProvideTaskPage method |
| GetPage |
HRESULT IProvideTaskPage::GetPage(
TASKPAGE tpType,
BOOL fPersistChanges,
HPROPSHEETPAGE * phPage
);
Provides the ability to retrieve one or more property sheet pages associated with a task object.
| TASKPAGE_TASK | General page property. |
| TASKPAGE_SCHEDULE | Schedule properties for the task object. |
| TASKPAGE_SETTINGS | Settings properties for the task object. |
See also TASKPAGE
Applications use the methods of the IScheduledWorkItem interface to control work items. The following list of methods is organized in vtable order.
HRESULT CreateTrigger(
WORD * piNewTrigger,
ITaskTrigger ** ppTrigger
);
Creates a task trigger.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
See also IScheduledWorkItem::DeleteTrigger
HRESULT DeleteTrigger(
WORD iTrigger
);
Deletes a task trigger.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
See also IScheduledWorkItem::CreateTrigger
HRESULT EditWorkItem(
HWND hParent,
DWORD dwReserved
);
Opens the configuration properties for the work item.
| S_OK | The operation was successful. |
| STG_E_NOTFILEBASEDSTORAGE | The task object is not persistent. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
When you open the Properties page for a task from Windows®, the Task Scheduler calls this method to display the task's properties.
HRESULT GetAccountInformation(
LPWSTR * ppwszAccountName
);
Retrieves the account name for the task. This method is for Windows NT®; it does nothing in Windows 95. The Task Scheduler service must be running for this method to succeed.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
The method that invokes GetAccountInformation is responsible for freeing the string using the CoTaskMemFree function.
See also IScheduledWorkItem::SetAccountInformation
HRESULT GetComment(
LPWSTR * ppwszComment
);
Retrieves the comment for the work item.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetCreator(
LPWSTR * ppwszCreator
);
Retrieves the work item's creator.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
See also IScheduledWorkItem::SetCreator
HRESULT GetErrorRetryCount(
WORD * pwRetryCount
);
Not currently implemented.
HRESULT GetErrorRetryInterval(
WORD * pwRetryInterval
);
Not currently implemented. Retrieves the time interval, in minutes, between task retries after an error occurs.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
| E_NOTIMPL | Not implemented. |
See also IScheduledWorkItem::SetErrorRetryInterval
HRESULT GetExitCode(
DWORD * pdwExitCode
);
Retrieves the work item's last exit code.
| S_OK | The attempt to start the work item was successful. |
| SCHED_S_TASK_HAS_NOT_RUN | No attempt has ever been made to start this work item. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetFlags(
DWORD * pdwFlags
);
Returns the flags that modify the task's behavior.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetIdleWait(
WORD * pwIdleMinutes,
WORD * pwDeadlineMinutes
);
Retrieves the task's idle wait time.
If the task has the TASK_EVENT_TRIGGER_ON_IDLE trigger, the task runs when pwIdleMinutes 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 after a period of pwDeadlineMinutes have elapsed with no mouse or keyboard activity. The Task Scheduler service will wait up to pwDeadlineMinutes past the scheduled start time of the task for the required pwIdleMinutes of idle time to elapse.
See also IScheduledWorkItem::SetIdleWait, Idle Triggers
HRESULT GetMostRecentRunTime(
SYSTEMTIME * pstLastRun
);
Retrieves the most recent time the work item began running.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
| SCHED_S_TASK_HAS_NOT_RUN | The task has never run. |
See also IScheduledWorkItem::GetNextRunTime
HRESULT GetNextRunTime(
[in, out] SYSTEMTIME * pstNextRun
);
Retrieves the next time the work item will run.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetRunTimes(
const LPSYSTEMTIME pstBegin,
const LPSYSTEMTIME pstEnd,
WORD * pCount,
LPSYSTEMTIME * rgstTaskTimes
);
Retrieves the work item run times for a specified time period.
| S_OK | The requested number of run times was retrieved. |
| S_FALSE | The method 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 work item 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 might cause the work item to run during the specified time period. |
| SCHED_S_TASK_NO_VALID_TRIGGERS | The work item is enabled but has no valid triggers. |
| SCHED_S_TASK_DISABLED | The work item is disabled. |
| E_INVALIDARG | One or more of the arguments are invalid. |
| E_OUTOFMEMORY | There is insufficient memory to compute the result. |
HRESULT GetStatus(
HRESULT * phrStatus
);
Retrieves the status of the work item.
| SCHED_S_TASK_READY | Task is ready to run at its next scheduled time. |
| SCHED_S_TASK_RUNNING | Task is currently running. |
| SCHED_S_TASK_NOT_SCHEDULED | One or more of the properties that are needed to run this task on a schedule have not been set. |
HRESULT GetTrigger(
WORD iTrigger,
ITaskTrigger ** ppTrigger
);
Retrieves a task trigger.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetTriggerCount(
WORD * plCount
);
Retrieves the number of triggers for the current task.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetTriggerString(
WORD iTrigger,
LPWSTR * ppwszTrigger
);
Retrieves a character string that describes the task trigger.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
HRESULT GetWorkItemData(
WORD * pcBytes,
BYTE ** ppBytes
);
Retrieves application-defined data associated with the work item.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
See also IScheduledWorkItem::SetWorkItemData
HRESULT Run(void);
Runs the work item. The Task Scheduler service must be running for this method to succeed.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
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. The Task Scheduler service must be running for this method to succeed.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
See also IScheduledWorkItem::GetAccountInformation
HRESULT SetComment(
LPCWSTR pwszComment
);
Sets the comment for the work item.
| S_OK | The operation was successful. |
| E_INVALIDARG | The arguments are not valid. |
| E_OUTOFMEMORY | Not enough memory is available. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.