Interfaces

Interfaces


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

IEnumWorkItems

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

IEnumWorkItems::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.

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

IEnumWorkItems::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.

celt
Number of tasks to retrieve.
rgpwszNames
Address of an array of pointers to character strings that 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 contains the number of tasks returned in rgpwszNames. If the celt parameter is 1, this parameter can be NULL.

IEnumWorkItems::Reset

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.

IEnumWorkItems::Skip

HRESULT Skip(
    ULONG celt
);

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

celt
Number of tasks to be skipped.

IProvideTaskPage

Applications use the method of the IProvideTaskPage interface to have access to the task object's property sheet settings.

IProvideTaskPage method
GetPage

IProvideTaskPage::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.

tpType
Specific page to return. The page type is one of the enumerated types of TASKPAGE defined as:
TASKPAGE_TASK General page property.
TASKPAGE_SCHEDULE Schedule properties for the task object.
TASKPAGE_SETTINGS Settings properties for the task object.
fPersistChanges
If TRUE, the page updates the persisted task object automatically if there is a change made on release. If FALSE, the caller is responsible for persisting task object changes by calling IPersistFile::Save on the task object.
phPage
Returned page handle for the task object.

See also TASKPAGE

IScheduledWorkItem

Applications use the methods of the IScheduledWorkItem interface to control work items. The following list of methods is organized in vtable order.

IScheduledWorkItem methods
CreateTrigger
DeleteTrigger
GetTriggerCount
GetTrigger
GetTriggerString
GetRunTimes
GetNextRunTime
SetIdleWait
GetIdleWait
Run
Terminate
EditWorkItem
GetMostRecentRunTime
GetStatus
GetExitCode
SetComment
GetComment
SetCreator
GetCreator
SetWorkItemData
GetWorkItemData
SetErrorRetryCount
GetErrorRetryCount
SetErrorRetryInterval
GetErrorRetryInterval
SetFlags
GetFlags
SetAccountInformation
GetAccountInformation

IScheduledWorkItem::CreateTrigger

HRESULT CreateTrigger(
    WORD * piNewTrigger,
    ITaskTrigger ** ppTrigger
);

Creates a task trigger.

piNewTrigger
Address of a value that specifies the new trigger. piNewTrigger receives the new trigger index value. DeleteTrigger would take this value to delete the trigger.
ppTrigger
Address of a pointer to an ITaskTrigger interface.

See also IScheduledWorkItem::DeleteTrigger

IScheduledWorkItem::DeleteTrigger

HRESULT DeleteTrigger(
    WORD iTrigger
);

Deletes a task trigger.

iTrigger
Value that specifies the trigger to be deleted. The value associated with a trigger is established when a trigger is created by CreateTrigger.

See also IScheduledWorkItem::CreateTrigger

IScheduledWorkItem::EditWorkItem

HRESULT EditWorkItem(
    HWND  hParent,
    DWORD dwReserved
);

Opens the configuration properties for the work item.

hParent
Handle to the parent window of the configuration properties window.
dwReserved
Reserved for internal use; this must be zero.

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

IScheduledWorkItem::GetAccountInformation

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.

ppwszAccountName
Address of an LPWSTR that contains the account name for the current task.

The method that invokes GetAccountInformation is responsible for freeing the string using the CoTaskMemFree function.

See also IScheduledWorkItem::SetAccountInformation

IScheduledWorkItem::GetComment

HRESULT GetComment(
    LPWSTR * ppwszComment
);

Retrieves the comment for the work item.

ppwszComment
Character string that contains the comment retrieved from the current work item.

IScheduledWorkItem::GetCreator

HRESULT GetCreator(
    LPWSTR * ppwszCreator
);

Retrieves the work item's creator.

ppwszCreator
Address of an LPWSTR that contains the current task's creator. The method that invokes GetCreator is responsible for freeing this string using the CoTaskMemFree function.

See also IScheduledWorkItem::SetCreator

IScheduledWorkItem::GetErrorRetryCount

HRESULT GetErrorRetryCount(
    WORD * pwRetryCount
);

Not currently implemented.

IScheduledWorkItem::GetErrorRetryInterval

HRESULT GetErrorRetryInterval(
    WORD * pwRetryInterval
);

Not currently implemented. Retrieves the time interval, in minutes, between task retries after an error occurs.

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

See also IScheduledWorkItem::SetErrorRetryInterval

IScheduledWorkItem::GetExitCode

HRESULT GetExitCode(
    DWORD * pdwExitCode
);

Retrieves the work item's last exit code.

pdwExitCode
Address of a value that is set to the exit code that the work item returned when it last stopped running. If the work item has never been started, this will be set to zero.

IScheduledWorkItem::GetFlags

HRESULT GetFlags(
    DWORD * pdwFlags
);

Returns the flags that modify the task's behavior.

pdwFlags
Address of a value that contains the description of how the task behaves. For a list of the flags, see IScheduledWorkItem::SetFlags.

IScheduledWorkItem::GetIdleWait

HRESULT GetIdleWait(
    WORD * pwIdleMinutes,
    WORD * pwDeadlineMinutes
);

Retrieves the task's idle wait time.

pwIdleMinutes
Address of a value that contains the current task's idle wait time.
pwDeadlineMinutes
Address of a value that specifies the maximum number of minutes to wait for the idle time duration contained in pwIdleMinutes to occur before running the task.

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

IScheduledWorkItem::GetMostRecentRunTime

HRESULT GetMostRecentRunTime(
    SYSTEMTIME * pstLastRun
);

Retrieves the most recent time the work item began running.

pstLastRun
Address of a SYSTEMTIME structure that contains the most recent time the current task ran.

See also IScheduledWorkItem::GetNextRunTime

IScheduledWorkItem::GetNextRunTime

HRESULT GetNextRunTime(
    [in, out] SYSTEMTIME * pstNextRun
);

Retrieves the next time the work item will run.

pstNextRun
Address of a SYSTEMTIME structure that contains the next time the work item will run.

IScheduledWorkItem::GetRunTimes

HRESULT GetRunTimes(
    const LPSYSTEMTIME pstBegin,
    const LPSYSTEMTIME pstEnd,
    WORD * pCount,
    LPSYSTEMTIME * rgstTaskTimes
);

Retrieves the work item run times for a specified time period.

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, 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 an array of SYSTEMTIME structures. This array contains pCount run times. This array must be freed using the CoTaskMemFree function.

IScheduledWorkItem::GetStatus

HRESULT GetStatus(
    HRESULT * phrStatus
);

Retrieves the status of the work item.

phrStatus
Address of a value that contains the status of the current work item. phrStatus can be set to one of the following values:
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.

IScheduledWorkItem::GetTrigger

HRESULT GetTrigger(
    WORD iTrigger, 
    ITaskTrigger ** ppTrigger
);

Retrieves a task trigger.

iTrigger
Value that specifies which trigger to retrieve.
ppTrigger
Address of a pointer to an ITaskTrigger interface. This interface contains the retrieved trigger.

IScheduledWorkItem::GetTriggerCount

HRESULT GetTriggerCount(
    WORD * plCount
);

Retrieves the number of triggers for the current task.

plCount
Address of a value that contains the total count of all triggers that are currently associated with the task.

IScheduledWorkItem::GetTriggerString

HRESULT GetTriggerString(
    WORD iTrigger, 
    LPWSTR * ppwszTrigger
);

Retrieves a character string that describes the task trigger.

iTrigger
Value that specifies which trigger to retrieve.
ppwszTrigger
Address of a character string that contains the retrieved trigger description.

IScheduledWorkItem::GetWorkItemData

HRESULT GetWorkItemData(
    WORD * pcBytes, 
    BYTE ** ppBytes
);

Retrieves application-defined data associated with the work item.

pcBytes
Number of bytes copied.
ppBytes
Address of a BYTE pointer that contains user-defined data for the current task. The method that invokes GetWorkItemData is responsible for freeing this memory by using CoTaskMemFree.

See also IScheduledWorkItem::SetWorkItemData

IScheduledWorkItem::Run

HRESULT Run(void);

Runs the work item. The Task Scheduler service must be running for this method to succeed.

IScheduledWorkItem::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. The Task Scheduler service must be running for this method to succeed.

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

See also IScheduledWorkItem::GetAccountInformation

IScheduledWorkItem::SetComment

HRESULT SetComment(
    LPCWSTR pwszComment
);

Sets the comment for the work item.

pwszComment
Character string containing the comment to assign to the current work item.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.