WMI_FUNCTION_CONTROL_CALLBACK回调函数（wmilib.h）

项目
02/07/2025

DpWmiFunctionControl 例程启用或禁用事件通知，并为驱动程序注册为成本高昂的数据块启用或禁用数据收集。此例程是可选的。

语法

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

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

参数

[in] DeviceObject

指向驱动程序的 WDM DEVICE_OBJECT 结构的指针。

[in] Irp

指向 IRP 的指针。

[in] GuidIndex

通过在传递给 WmiSystemControl的 WMILIB_CONTEXT 结构中提供的驱动程序提供的 GUID 列表中提供从零开始的索引来指定数据块。

[in] Function

指定要启用或禁用的内容。 WmiEventControl 指示事件，WmiDataBlockControl 指示注册为成本高昂的块的数据收集（也就是说，驱动程序在标志WMIGUIDREGINFO 结构中设置WMIREG_FLAG_EXPENSIVE块）的数据收集。

[in] Enable

指定 TRUE 以启用事件或数据收集，或 FALSE 禁用它。

返回值

DpWmiFunctionControl 返回STATUS_SUCCESS或适当的错误状态，例如：

言论

WMI 调用驱动程序的 DpWmiFunctionControl 例程后，驱动程序调用 WmiSystemControl，以响应以下请求之一：

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

如果驱动程序实现 DpWmiFunctionControl 例程，驱动程序必须将例程的地址放在 WmiFunctionControl 传递给 WmiSystemControl的 WMILIB_CONTEXT 结构的成员中。如果驱动程序未实现 DpWmiFunctionControl 例程，则必须将 WmiFunctionControl 设置为 NULL。在后一种情况下，WMI 将STATUS_SUCCESS返回给调用方。

驱动程序负责验证所有输入参数。具体而言，驱动程序必须执行以下作：

根据 WMILIB_CONTEXT 结构的 GuidCount 成员，验证 GuidIndex 值是否介于零和 GuidCount-1 之间。
验证驱动程序是否已标记指定的数据块以供删除。如果驱动程序最近在 WMIGUIDREGINFO 中指定了WMIREG_FLAG_REMOVE_GUID标志，结构中包含的 WMILIB_CONTEXT 结构，则可能需要在删除之前收到其他请求。

驱动程序不需要检查事件或数据收集是否已为块启用，因为 WMI 在第一个数据使用者启用块时发送单个启用请求，并在最后一个数据使用者禁用块时发送单个禁用请求。 WMI 不会调用 DpWmiFunctionControl 来启用块，而无需进行干预调用来禁用它。

为块启用或禁用事件或数据收集后，驱动程序将调用 WmiCompleteRequest 以完成请求。

此例程可以分页。

有关实现此例程的详细信息，请参阅调用 WmiSystemControl 来处理 WMI IRP。