WMI_FUNCTION_CONTROL_CALLBACK回调函数 (wmilib.h)

项目
08/08/2023

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 在驱动程序调用 WmiSystemControl 以响应以下请求之一后调用驱动程序的 DpWmiFunctionControl 例程：

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

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

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

根据 WMILIB_CONTEXT 结构的 GuidCount 成员，验证 GuidIndex 值是否介于 0 和 GuidCount-1 之间。
验证驱动程序是否未标记要删除的指定数据块。如果驱动程序最近在 WMILIB_CONTEXT 结构中包含的 WMIGUIDREGINFO 结构中指定 了 WMIREG_FLAG_REMOVE_GUID 标志，则可能会有额外的请求在删除发生之前到达。

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

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

此例程可以分页。

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