[This is preliminary documentation and subject to change.]
The SetThreadExecutionState function enables applications to inform the system that it is in use, thereby preventing the system from entering the sleeping power state while the application is running.
EXECUTION_STATE SetThreadExecutionState(
EXECUTION_STATE esFlags // execution requirements
);
| Flag | Description |
|---|---|
| ES_SYSTEM_REQUIRED | Informs the system that the thread is performing some operation that is not normally detected as activity by the system. |
| ES_DISPLAY_REQUIRED | Informs the system that the thread is performing some operation that is not normally detected as display activity by the system. |
| ES_CONTINUOUS | Informs the system that the state being set should remain in effect until the next call that uses ES_CONTINUOUS and one of the other state flags is cleared. |
If the function succeeds, the return value is the previous thread execution state.
If the function fails, the return value is NULL.
Activities that are automatically detected include local keyboard or mouse input, server activity, and changing window focus. Activities that are not automatically detected include disk or CPU activity and video display.
Calling SetThreadExecutionState with ES_SYSTEM_REQUIRED prevents the system from putting the computer in the sleeping state by resetting the system idle timer. Calling SetThreadExecutionState with ES_DISPLAY_REQUIRED prevents the system from turning off the display by resetting the display idle timer. Calling SetThreadExecutionState without ES_CONTINUOUS simply resets the idle timer; to keep the display or system in the working state, the thread must call SetThreadExecutionState periodically.
To run properly on a power-managed computer, applications such as fax servers, answering machines, backup agents, and network management applications must use ES_SYSTEM_REQUIRED | ES_CONTINUOUS when they process events. Multimedia applications, such as video players and presentation applications, must use ES_DISPLAY_REQUIRED when they display video for long periods of time without user input. Applications such as word processors, spreadsheets, browsers, and games do not need to call SetThreadExecutionState.
Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
Power Management Overview, Power Management Functions, SetSystemPowerState, WM_POWERBROADCAST