Función PoRegisterPowerSettingCallback (wdm.h)

Artículo
02/29/2024

La rutina PoRegisterPowerSettingCallback registra una rutina de devolución de llamada de configuración de energía para recibir notificaciones de cambios en la configuración de energía especificada.

Sintaxis

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

Parámetros

[in, optional] DeviceObject

Puntero a una estructura de DEVICE_OBJECT asociada al autor de la llamada de esta rutina. Este parámetro es opcional. Se usa internamente solo para fines de depuración. Si no se proporciona este parámetro, debe establecerse en NULL.

[in] SettingGuid

Puntero al GUID que representa la configuración de energía de este registro. Cuando cambia la configuración de energía especificada, el administrador de energía llama a la rutina de devolución de llamada para notificar al controlador del cambio y para proporcionar el nuevo valor de la configuración. Para obtener más información, vea la sección Comentarios.

[in] Callback

Puntero a una rutina de devolución de llamada implementada por el autor de la llamada que el administrador de energía llama cuando cambia la configuración de energía especificada. Para ver el prototipo funcional de la rutina de devolución de llamada, consulte Devolución de llamada de configuración de energía.

[in, optional] Context

Puntero al contexto de la rutina de devolución de llamada. Este parámetro es opcional. Se proporciona para que un controlador o contexto de dispositivo se pueda pasar a la rutina de devolución de llamada. Si no se usa este parámetro, debe establecerse en NULL.

[out] Handle

Identificador que usa el administrador de energía para representar la rutina de devolución de llamada. Posteriormente, un controlador debe proporcionar este identificador en una llamada a PoUnregisterPowerSettingCallback para anular el registro de la rutina de devolución de llamada.

Valor devuelto

PoRegisterPowerSettingCallback devuelve una de las siguientes opciones:

Código devuelto	Descripción
STATUS_SUCCESS	La rutina registró la rutina de devolución de llamada.
STATUS_INSUFFICIENT_RESOURCES	La rutina no pudo asignar los recursos del sistema necesarios para registrar la rutina de devolución de llamada.

Comentarios

Un controlador llama a PoRegisterPowerSettingCallback para registrar una rutina de devolución de llamada con el administrador de energía. El administrador de energía llama posteriormente a esta rutina de devolución de llamada para notificar al controlador después de que haya un cambio en la configuración de alimentación especificada. Además, el administrador de energía inicializa la configuración de energía del controlador llamando inmediatamente a la rutina de devolución de llamada y pasando el valor actual de la configuración de energía. El administrador de energía inicializa la configuración de energía del controlador de esta manera, independientemente de si la configuración de energía ha cambiado realmente.

Un controlador debe llamar a PoRegisterPowerSettingCallback para cada configuración de alimentación que el controlador necesite supervisar. Los controladores deben llamar a esta rutina en su rutina DriverEntry durante la inicialización. Normalmente, la mayoría de los controladores pasan un puntero a una extensión de dispositivo en el parámetro Context .

Para anular el registro de una devolución de llamada de configuración de energía, llame a la rutina PoUnregisterPowerSettingCallback .

Normalmente, Kernel-Mode controladores de Driver Framework (KMDF) deben llamar a PoRegisterPowerSettingCallback desde su función de devolución de llamada EvtDeviceSelfManagedIoInit y deben llamar a PoUnregisterPowerSettingCallback desde su función de devolución de llamada EvtDeviceSelfManagedIoCleanup . Estos controladores no deben llamar a PoRegisterPowerSettingCallback desde su función de devolución de llamada EvtDriverDeviceAdd ; De lo contrario, se podría llamar a la rutina de devolución de llamada de configuración de energía antes de que la pila de controladores se cree completamente.

Se llama a la rutina de devolución de llamada registrada para una configuración de energía determinada cuando se produce una transición en estado de energía que cambia el valor de la configuración o cuando el administrador de energía cambia el valor de la configuración. Por ejemplo, si SettingGuid apunta al valor GUID GUID_LIDSWITCH_STATE_CHANGE, se llama a la rutina de devolución de llamada cuando la tapa de un equipo portátil hace clic en abrir o cerrar. El parámetro Value pasado a la rutina de devolución de llamada de este ejemplo apunta a un valor de ULONG que es 1 si el estado del modificador de tapa ha cambiado de cerrado a abierto y es 0 si el estado del modificador de tapa ha cambiado de abierto a cerrado. Para obtener más información, vea las definiciones de GUID de configuración de energía y comentarios extensos en el archivo de encabezado Wdm.h.

La llamada inicial a una rutina de devolución de llamada puede producirse inmediatamente, antes de que la llamada PoRegisterPowerSettingCallback que registre la rutina devuelve.

Solo se puede llamar a PoRegisterPowerSettingCallback en IRQL = PASSIVE_LEVEL.

devolución de llamada de Power-Setting

El prototipo de función de la rutina de devolución de llamada de configuración de energía es el siguiente:

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

Los parámetros de devolución de llamada de configuración de energía son:

SettingGuid
Puntero a un GUID que representa la configuración de energía que cambió. La configuración de energía y sus GUID correspondientes se definen en Wdm.h.

Valor
Puntero al nuevo valor de la configuración de energía que cambió.

ValueLength
Valor de tipo ULONG que especifica el tamaño, en bytes, del nuevo valor de configuración de energía.

Contexto
Puntero al contexto que un controlador proporcionó en la llamada a PoRegisterPowerSettingCallback que registró la rutina de devolución de llamada.

El administrador de energía llama a una devolución de llamada de configuración de energía en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una rutina de devolución de llamada de configuración de energía, primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada de configuración de energía denominada MyPowerSettingCallback, use el tipo POWER_SETTING_CALLBACK como se muestra en este ejemplo de código:

POWER_SETTING_CALLBACK MyPowerSettingCallback;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

El tipo de función POWER_SETTING_CALLBACK se define en el archivo de encabezado Wdm.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función POWER_SETTING_CALLBACK en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)