Función SetThreadExecutionState (winbase.h)

Artículo
08/27/2023

Permite a una aplicación informar al sistema de que está en uso, lo que impide que el sistema entre en suspensión o desactive la pantalla mientras se ejecuta la aplicación.

Sintaxis

EXECUTION_STATE SetThreadExecutionState(
  [in] EXECUTION_STATE esFlags
);

Parámetros

[in] esFlags

Requisitos de ejecución del subproceso. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
ES_AWAYMODE_REQUIRED 0x00000040	Habilita el modo de distancia. Este valor debe especificarse con ES_CONTINUOUS. El modo de distancia solo se debe usar en las aplicaciones de grabación multimedia y distribución de medios que deben realizar un procesamiento en segundo plano crítico en equipos de escritorio mientras el equipo parece estar en suspensión. Vea la sección Comentarios.
ES_CONTINUOUS 0x80000000	Informa al sistema de que el estado que se establece debe permanecer en vigor hasta que se borre la siguiente llamada que usa ES_CONTINUOUS y una de las otras marcas de estado.
ES_DISPLAY_REQUIRED 0x00000002	Obliga a que la pantalla esté activada restableciendo el temporizador de inactividad de la pantalla.
ES_SYSTEM_REQUIRED 0x00000001	Obliga al sistema a estar en estado de trabajo restableciendo el temporizador de inactividad del sistema.
ES_USER_PRESENT 0x00000004	Este valor no se admite. Si ES_USER_PRESENT se combina con otros valores de esFlags , se producirá un error en la llamada y no se establecerá ninguno de los estados especificados.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el estado de ejecución del subproceso anterior.

Si la función no se realiza correctamente, el valor devuelto es NULL.

Comentarios

El sistema detecta automáticamente actividades como el teclado local o la entrada del mouse, la actividad del servidor y el cambio del foco de ventana. Las actividades que no se detectan automáticamente incluyen la actividad de disco o CPU y la presentación de vídeo.

Llamar a SetThreadExecutionState sin ES_CONTINUOUS simplemente restablece el temporizador de inactividad; para mantener la pantalla o el sistema en estado de trabajo, el subproceso debe llamar a SetThreadExecutionState periódicamente.

Para ejecutarse correctamente en un equipo administrado con energía, las aplicaciones como los servidores de fax, las máquinas de respuesta, los agentes de copia de seguridad y las aplicaciones de administración de red deben usar tanto ES_SYSTEM_REQUIRED comoES_CONTINUOUS cuando procesan eventos. Las aplicaciones multimedia, como los reproductores de vídeo y las aplicaciones de presentación, deben usar ES_DISPLAY_REQUIRED cuando muestren vídeo durante largos períodos de tiempo sin la entrada del usuario. Las aplicaciones como procesadores de texto, hojas de cálculo, exploradores y juegos no necesitan llamar a SetThreadExecutionState.

El valor de ES_AWAYMODE_REQUIRED solo se debe usar cuando sea absolutamente necesario para las aplicaciones multimedia que requieren que el sistema realice tareas en segundo plano, como grabar contenido de televisión o transmitir contenido multimedia a otros dispositivos mientras el sistema parece estar en suspensión. Las aplicaciones que no requieren un procesamiento en segundo plano crítico o que se ejecutan en equipos portátiles no deben habilitar el modo de distancia, ya que impide que el sistema conserve energía al entrar en suspensión verdadera.

Para habilitar el modo de distancia, una aplicación usa tanto ES_AWAYMODE_REQUIRED comoES_CONTINUOUS; para deshabilitar el modo de distancia, una aplicación llama a SetThreadExecutionState con ES_CONTINUOUS y borra ES_AWAYMODE_REQUIRED. Cuando el modo de distancia está habilitado, cualquier operación que colocaría el equipo en modo inactivo lo coloca en modo de distancia en su lugar. Parece que el equipo está en suspensión mientras el sistema sigue realizando tareas que no requieren la entrada del usuario. El modo de distancia no afecta al temporizador de inactividad de suspensión; para evitar que el sistema entre en suspensión cuando expire el temporizador, una aplicación también debe establecer el valor de ES_SYSTEM_REQUIRED .

La función SetThreadExecutionState no se puede usar para evitar que el usuario ponga el equipo en suspensión. Las aplicaciones deben respetar que el usuario espera un comportamiento determinado cuando cierre la tapa en su portátil o presione el botón de encendido.

Esta función no impide que el protector de pantalla se ejecute.

Ejemplos

// Television recording is beginning. Enable away mode and prevent
// the sleep idle time-out.
//
SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_AWAYMODE_REQUIRED);

//
// Wait until recording is complete...
//

//
// Clear EXECUTION_STATE flags to disable away mode and allow the system to idle to sleep normally.
//
SetThreadExecutionState(ES_CONTINUOUS);

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll