IScheduledWorkItem::GetIdleWait method (mstask.h)

Article
10/13/2021

[[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

Requirement	Value
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