WMI_FUNCTION_CONTROL_CALLBACK función de devolución de llamada (wmilib.h)

Artículo
02/07/2025

El DpWmiFunctionControl rutina habilita o deshabilita la notificación de eventos y habilita o deshabilita la recopilación de datos para los bloques de datos que el controlador registró como costoso de recopilar. Esta rutina es opcional.

Sintaxis

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Parámetros

[in] DeviceObject

Puntero a la estructura DEVICE_OBJECT WDM del controlador.

[in] Irp

Puntero al IRP.

[in] GuidIndex

Especifica el bloque de datos proporcionando un índice de base cero en la lista de GUID que el controlador proporcionó en la estructura de WMILIB_CONTEXT que pasó a WmiSystemControl.

[in] Function

Especifica qué habilitar o deshabilitar. WmiEventControl indica un evento y WmiDataBlockControl indica la recopilación de datos de un bloque que se registró como caro de recopilar (es decir, un bloque para el que el controlador estableció WMIREG_FLAG_EXPENSIVE en Marcas de la estructura WMIGUIDREGINFO que se usó para registrar el bloque).

[in] Enable

Especifica TRUE para habilitar el evento o la recopilación de datos, o FALSE deshabilitarlo.

Valor devuelto

dpWmiFunctionControl devuelve STATUS_SUCCESS o un estado de error adecuado, como:

Observaciones

WMI llama a la rutina de dpWmiFunctionControl de un controlador después de que el controlador llame a WmiSystemControl en respuesta a una de las siguientes solicitudes:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

Si un controlador implementa una rutina de DpWmiFunctionControl, el controlador debe colocar la dirección de la rutina en el WmiFunctionControl miembro de la estructura WMILIB_CONTEXT que pasa a WmiSystemControl. Si un controlador no implementa una rutina de DpWmiFunctionControl, debe establecer WmiFunctionControl en NULL. En este último caso, WMI devuelve STATUS_SUCCESS al autor de la llamada.

El controlador es responsable de validar todos los argumentos de entrada. En concreto, el controlador debe hacer lo siguiente:

Compruebe que el valor guidIndex de está entre cero y GuidCount-1, en función del miembro guidCount de de la estructura de WMILIB_CONTEXT.
Compruebe que el controlador no ha marcado el bloque de datos especificado para su eliminación. Si el controlador especificó recientemente la marca WMIREG_FLAG_REMOVE_GUID en un WMIGUIDREGINFO estructura contenida en una estructura de WMILIB_CONTEXT, es posible que llegue una solicitud adicional antes de que se produzca la eliminación.

No es necesario que el controlador compruebe si los eventos o la recopilación de datos ya están habilitados para un bloque, ya que WMI envía una única solicitud de habilitación cuando el primer consumidor de datos habilita el bloque y envía una única solicitud de deshabilitación cuando el último consumidor de datos deshabilita el bloque. WMI no llamará a dpWmiFunctionControl para habilitar un bloque sin una llamada intermedia para deshabilitarla.

Después de habilitar o deshabilitar el evento o la recopilación de datos para el bloque, el controlador llama a WmiCompleteRequest para completar la solicitud.

Esta rutina puede ser paginable.

Para obtener más información sobre la implementación de esta rutina, vea Llamada a WmiSystemControl para controlar irps de WMI.