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

Artículo
08/08/2023

La rutina DpWmiFunctionControl 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 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 de 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 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 usada para registrar el bloque).

[in] Enable

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

Valor devuelto

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

Comentarios

WMI llama a la rutina 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 DpWmiFunctionControl , el controlador debe colocar la dirección de la rutina en el miembro WmiFunctionControl de la estructura WMILIB_CONTEXT que pasa a WmiSystemControl. Si un controlador no implementa una rutina DpWmiFunctionControl , debe establecer WmiFunctionControl en NULL. En el ú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 está entre cero y GuidCount-1, en función del miembro GuidCount de la estructura 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 una estructura WMIGUIDREGINFO 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 deshabilitarlo.

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 cómo implementar esta rutina, vea Llamar a WmiSystemControl para controlar irP de WMI.