IScheduledWorkItem::SetCreator
Interfaces

IScheduledWorkItem::SetCreator


HRESULT SetCreator(
    LPCWSTR pwszCreator
);

Sets the work item's creator.

pwszCreator
LPCWSTR that contains the work item's creator.

See also IScheduledWorkItem::GetCreator

IScheduledWorkItem::SetErrorRetryCount

HRESULT SetErrorRetryCount(
    WORD wRetryCount
);

Not currently implemented. Sets the number of times the task will try to run again if an error occurs.

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

See also IScheduledWorkItem::GetErrorRetryCount

IScheduledWorkItem::SetErrorRetryInterval

HRESULT SetErrorRetryInterval(
    WORD wRetryInterval
);

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

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

See also IScheduledWorkItem::GetErrorRetryInterval

IScheduledWorkItem::SetFlags

HRESULT SetFlags(
    DWORD dwFlags
);

Sets the flags that modify the task's behavior.

dwFlags
Value that contains a combination of one or more of the following flags:
TASK_FLAG_INTERACTIVE
This task flag is used when converting Windows NT AT service jobs into tasks. The Windows NT AT service job refers to At.exe, the Windows NT command-line utility used for creating jobs for the Windows NT Schedule service. The Task Scheduler service replaces the Schedule service and is backward-compatible with it. This conversion occurs when the Task Scheduler is installed on Windows NT; for example, installing Internet Explorer 4.0, or upgrading to Windows NT 5. During the setup process, the Task Scheduler installation code searches the registry for jobs created for the AT service, and creates tasks that will accomplish the same operation.

For such converted jobs, the interactive flag is set if the task is intended to be displayed to the user. When this flag is not set, no task items are displayed in the Tasks folder, and no user interface associated with the task is presented to the user when the task is executed.

TASK_FLAG_DELETE_WHEN_DONE
Task will be deleted when there are no more scheduled run times.
TASK_FLAG_DISABLED
Task is disabled. This is useful to temporarily prevent a task from running at the scheduled time(s).
TASK_FLAG_HIDDEN
Task file is hidden. When the task begins execution, it runs in a hidden window.
TASK_FLAG_START_ONLY_IF_IDLE
Task begins only if the computer is not in use at the scheduled start time. Windows 95 only.
TASK_FLAG_KILL_ON_IDLE_END
Task terminates if the computer makes an idle to non-idle transition while the task is running. The computer is not considered idle until the IdleWait triggers' time elapses with no user input. Windows 95 only. For information regarding idle triggers, see Idle Triggers.
TASK_FLAG_RESTART_ON_IDLE_RESUME
Task starts again if the computer makes a non-idle to idle transition before all its triggers' dwMinutesDuration elapse. (Use this flag in conjunction with TASK_FLAG_KILL_ON_IDLE_END.) Windows 95 only.
TASK_FLAG_DONT_START_IF_ON_BATTERIES
Task does not start if its target computer is running on battery power. Windows 95 only.
TASK_FLAG_KILL_IF_GOING_ON_BATTERIES
Task ends and the associated application quits if the task's target computer switches to battery power. Windows 95 only.
TASK_FLAG_RUN_IF_CONNECTED_TO_INTERNET
Task runs only if there is currently a valid Internet connection. Note: This feature is currently not implemented.

See also IScheduledWorkItem::GetFlags

IScheduledWorkItem::SetIdleWait

HRESULT SetIdleWait(
    WORD wIdleMinutes,
    WORD wDeadlineMinutes
);

Sets the idle wait time for the task.

wIdleMinutes
Value of the task's idle wait time, in minutes.
wDeadlineMinutes
Value that specifies the maximum number of minutes to wait for the idle wait time duration contained in wIdleMinutes to occur before running the task.

If the task has the TASK_EVENT_TRIGGER_ON_IDLE trigger, the task runs when wIdleMinutes have elapsed since the most recent keyboard or mouse event.

If the TASK_FLAG_START_ONLY_IF_IDLE flag is set, the task runs only after a period of wIdleMinutes elapses with no mouse or keyboard activity. The Task Scheduler service will wait up to wDeadlineMinutes past the scheduled start time of the task for the required wIdleMinutes of idle time to elapse.

See also IScheduledWorkItem::GetIdleWait, Idle Triggers

IScheduledWorkItem::SetWorkItemData

HRESULT SetWorkItemData(
    WORD cBytes, 
    BYTE rgbData[]
);

Stores application-defined data associated with the work item.

cBytes
Number of bytes in the data buffer. The caller allocates and frees this memory.
rgbData
Data to copy.

See also IScheduledWorkItem::GetWorkItemData

IScheduledWorkItem::Terminate

HRESULT Terminate(void);

Ends the execution of the work item.

ITaskScheduler

Applications use the methods of the ITaskScheduler interface to schedule tasks. The following list of methods is organized in vtable order.

ITaskScheduler methods
SetTargetComputer
GetTargetComputer
Enum
Activate
Delete
NewWorkItem
AddWorkItem
IsOfType

ITaskScheduler::Activate

HRESULT Activate(
    LPCWSTR pwszName, 
    REFIID riid,
    IUnknown ** ppunk
);

Returns an active interface to the specified task.

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 receives the requested interface.

ITaskScheduler::AddWorkItem

HRESULT AddWorkItem(
    LPCWSTR  pwszTaskName,
    IScheduledWorkItem * pWorkItem
);

Adds a task to the schedule of tasks. Unlike NewWorkItem, this method requires that you first create an object that supports the IScheduledWorkItem interface and pass its address in the pWorkItem parameter.

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.
pWorkItem
Address of an interface pointer that receives the requested interface.

See also ITaskScheduler::NewWorkItem

ITaskScheduler::Delete

HRESULT Delete(
    LPCWSTR pwszName
);

Deletes a task.

pwszName
LPCWSTR that specifies the name of the task to delete.

ITaskScheduler::Enum

HRESULT Enum(
    IEnumTasks ** ppEnumTasks
);

Retrieves a pointer to an OLE enumerator object that enumerates the tasks in the current task folder.

ppEnumTasks
Address of a pointer to an IEnumWorkItems interface. This interface contains the enumeration context of the current task(s).

The current folder resides on the computer returned by GetTargetComputer, which defaults to the local computer if not previously set by a call to SetTargetComputer.

ITaskScheduler::GetTargetComputer

HRESULT GetTargetComputer(
    LPWSTR * ppwszComputer
);

Returns the computer name on which ITaskScheduler is currently targeted.

ppwszComputer
Address of an LPWSTR that contains the name of the target computer for the current task. This string is allocated by the method that invokes GetTargetComputer and is freed by the same method by using CoTaskMemFree.

ITaskScheduler::IsOfType

HRESULT IsOfType(
    LPCWSTR  pwszName,
    REFIID   riid
);

Checks the object's type to verify that it supports a particular interface.

pwszName
LPCWSTR that specifies the name of the object to check.
riid
Identifier of the interface to be matched.

ITaskScheduler::NewWorkItem

HRESULT NewWorkItem(
    LPCWSTR    pwszTaskName,
    REFCLSID   rclsid,
    REFIID     riid,
    IUnknown   ** ppunk
);

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

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.
rclsid
Identifier of the class of work item to be created. The only supported class is CLSID_Ctask.
riid
Reference identifier of the interface being requested.
ppunk
Address of an interface pointer that receives the requested interface.

See also ITaskScheduler::AddWorkItem

ITaskScheduler::SetTargetComputer

HRESULT SetTargetComputer(
    LPCWSTR pwszComputer
);

Selects the computer that the ITaskScheduler 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.

pwszComputer
LPCWSTR that specifies the target computer for the current task. The computer name indicates that the local computer is the target computer; set this value to NULL or to the local computer's Universal Naming Convention (UNC) name.

ITask

Applications use the methods of the ITask interface to set and retrieve task information and to run and terminate tasks. The following list of methods is organized in vtable order.

ITask methods
SetApplicationName
GetApplicationName
SetParameters
GetParameters
SetWorkingDirectory
GetWorkingDirectory
SetPriority
GetPriority
SetTaskFlags
GetTaskFlags
SetMaxRunTime
GetMaxRunTime

ITask::GetApplicationName

HRESULT GetApplicationName(
    LPWSTR * ppwszApplicationName
);

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

ppwszApplicationName
Address of an LPWSTR that contains the name of the application the current task is associated with. The method that invokes GetApplicationName is responsible for freeing this string using the CoTaskMemFree function.

If you set the application name property to an executable file, you can set the parameters property to the command-line arguments to pass to that executable—for example, ApplicationName=notepad.exe and Parameters=foo.txt.

However, if you set the ApplicationName property to a non-executable file, the parameters property will be ignored, because the application name in this case is the parameter—for example, ApplicationName=foo.txt.

See also ITask::SetApplicationName

ITask::GetMaxRunTime

HRESULT GetMaxRunTime(
    DWORD * pdwMaxRunTime
);

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

pdwMaxRunTime
Address of a value that contains 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, TerminateProcess is run.

See also ITask::SetMaxRunTime

ITask::GetParameters

HRESULT GetParameters(
    LPWSTR * ppwszParameters
);

Retrieves the task's command-line parameters.

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

See also ITask::SetParameters

ITask::GetPriority

HRESULT GetPriority(
    DWORD * pdwPriority
);

Retrieves the priority for the task.

pdwPriority
Address of a DWORD that contains 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

See also ITask::SetPriority

ITask::GetTaskFlags

HRESULT GetTaskFlags(
    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 ITask::SetTaskFlags.

ITask::GetWorkingDirectory

HRESULT GetWorkingDirectory(
    LPWSTR * ppwszWorkingDirectory
);

Retrieves the task's working directory.

ppwszWorkingDirectory
Address of an LPWSTR that contains the task's working directory. The method that invokes GetWorkingDirectory is responsible for freeing this string using the CoTaskMemFree function.

See also ITask::SetWorkingDirectory

ITask::SetApplicationName

HRESULT SetApplicationName(
    LPCWSTR pwszApplicationName
);

Assigns a specific application to the current task.

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, the Task Scheduler searches 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.

See also ITask::GetApplicationName

ITask::SetMaxRunTime

HRESULT SetMaxRunTime(
    DWORD dwMaxRunTime
);

Sets the maximum time the task can run before terminating.

dwMaxRunTime
Value assigned as the maximum run time, in milliseconds, for 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 has not exited within three minutes, TerminateProcess is run.

See also ITask::GetMaxRunTime

ITask::SetParameters

HRESULT SetParameters(
    LPCWSTR pwszParameters
);

Sets the command-line parameters for the task.

pwszParameters
LPCWSTR that contains task parameters. These parameters are passed as command-line arguments to the application the task will run.

If the Application Name method contains a document to run by association, the Parameters methods are ignored. To clear the command-line parameter property, set pwszParameters to L"".

The application name and parameters properties are accessed through the Application Name Set and Get methods on the ITask interface. They are properties of a task object.

See also ITask::GetParameters

ITask::SetPriority

HRESULT SetPriority(
    DWORD dwPriority
);

Sets the priority for the task.

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

See also ITask::GetPriority

ITask::SetTaskFlags

HRESULT SetTaskFlags(
    DWORD dwFlags
);

Sets the flags that modify the task's behavior.

dwFlags
Value that contains a combination of one or more of the following flags:
TASK_FLAG_INTERACTIVE
This task flag is used when converting Windows NT AT service jobs into tasks. The Windows NT AT service job refers to At.exe, the Windows NT command-line utility used for creating jobs for the Windows NT Schedule service. The Task Scheduler service replaces the Schedule service and is backward-compatible with it. This conversion occurs when the Task Scheduler is installed on Windows NT: for example, installing Internet Explorer 4.0, or upgrading to Windows NT 5. During the setup process, the Task Scheduler installation code searches the registry for jobs created for the AT service, and creates tasks that will accomplish the same operation.

For such converted jobs, the interactive flag is set if the task is intended to be displayed to the user. When this flag is not set, no task items are displayed in the Tasks folder, and no user interface associated with the task is presented to the user when the task is executed.

TASK_FLAG_DELETE_WHEN_DONE
Task will be deleted when there are no more scheduled run times.
TASK_FLAG_DISABLED
Task is disabled. This is useful to temporarily prevent a task from running at the scheduled time(s).
TASK_FLAG_HIDDEN
Task file is hidden. When the task begins execution, it runs in a hidden window.
TASK_FLAG_START_ONLY_IF_IDLE
Task begins only if the computer is not in use at the scheduled start time. Windows 95 only.
TASK_FLAG_KILL_ON_IDLE_END
Task terminates if the computer makes an idle to non-idle transition while the task is running. The computer is not considered idle until the IdleWait triggers' time elapses with no user input. Windows 95 only. For information regarding idle triggers, see Idle Triggers.
TASK_FLAG_DONT_START_IF_ON_BATTERIES
Task does not start if its target computer is running on battery power. Windows 95 only.
TASK_FLAG_KILL_IF_GOING_ON_BATTERIES
Task ends and the associated application quits if the task's target computer switches to battery power. Windows 95 only.
TASK_FLAG_RUN_IF_CONNECTED_TO_INTERNET
Not yet implemented.

See also ITask::GetTaskFlags

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