IScheduledWorkItem::GetIdleWait method (mstask.h)

[[This API may be altered or unavailable in subsequent versions of the operating system or product. Please use the Task Scheduler 2.0 Interfaces instead.] ]

Retrieves the idle wait time for the work item.

For information about idle conditions, see Task Idle Conditions.

Syntax

HRESULT GetIdleWait(
  [out] WORD *pwIdleMinutes,
  [out] WORD *pwDeadlineMinutes
);

Parameters

[out] pwIdleMinutes

A pointer to a WORD that contains the idle wait time for the current work item, in minutes.

[out] pwDeadlineMinutes

A pointer to a WORD that specifies the maximum number of minutes that the Task Scheduler will wait for the idle-time period returned in pwIdleMinutes.

Return value

The GetIdleWait method returns one of the following values.

Return code Description
S_OK
The operation was successful.
E_INVALIDARG
The arguments are not valid.

Remarks

The idle time returned here is used in conjunction with idle triggers and idle conditions. Idle triggers are event-based triggers that are not associated with a scheduled time. Idle conditions are associated with the scheduled start time for the task.

Idle triggers are specified by setting the TASK_TRIGGER_TYPE member of the TASK_TRIGGER structure to the value TASK_EVENT_TRIGGER_ON_IDLE. The idle trigger is fired when the system becomes idle for the amount of time returned in pwIdleMinutes.

You can set idle conditions by calling IScheduledWorkItem::SetFlags. If the TASK_FLAG_START_ONLY_IF_IDLE flag is set, the work item runs at its scheduled time only if the system becomes idle for the amount of time returned in pwIdleMinutes. The Task Scheduler service will wait up to pwDeadlineMinutes past the scheduled start time to see if the system becomes idle.

Examples

For an example of how to retrieve the idle wait time of a task, see C/C++ Code Example: Retrieving Task Idle-wait Time.

Requirements

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header mstask.h
Library Mstask.lib
DLL Mstask.dll
Redistributable Internet Explorer 4.0 or later on Windows NT 4.0 and Windows 95

See also

IScheduledWorkItem

IScheduledWorkItem::SetIdleWait