WMI_QUERY_REGINFO_CALLBACK回调函数 (wmilib.h)

项目
08/08/2023

DpWmiQueryReginfo 例程提供有关驱动程序要注册的数据块和事件块的信息。此例程是必需的。

语法

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

参数

[in] DeviceObject

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

[out] RegFlags

此参数指示正在注册的所有块的常见特征。 RegFlags 中设置的任何标志都应用于所有块。驱动程序可以通过在块的 WMIGUIDREGINFO 结构中设置标志来补充给定块的 RegFlag。例如，驱动程序可能会清除 RegFlags 中的WMIREG_FLAG_EXPENSIVE，但在标志中将其设置为将给定块注册为收集成本高昂的块。

驱动程序在 RegFlags 中设置以下标志之一：

WMIREG_FLAG_INSTANCE_BASENAME

请求 WMI 根据驱动程序在 InstanceName 中提供的基名称生成静态 实例名称。 WMI 通过将计数器追加到基名称来生成实例名称。

WMIREG_FLAG_INSTANCE_PDO

请求 WMI 从 PDO 的设备实例 ID 生成静态实例名称。如果驱动程序设置了此标志，则还必须将 Pdo 设置为传递给驱动程序的 AddDevice 例程的 PDO。 WMI 从 PDO 的设备实例路径生成实例名称。使用设备实例路径作为静态实例名称的基础是高效的，因为此类名称保证是唯一的。 WMI 自动提供实例的“友好”名称，作为数据块中可由数据使用者查询的项。

驱动程序还可以在 RegFlags 中设置以下一个或多个标志，但更常见的情况是在块的 WMIGUIDREGINFO 结构的标志中设置它们：

WMIREG_FLAG_EVENT_ONLY_GUID

块只能作为事件启用或禁用，不能查询或设置。如果此标志是清除的，则还可以查询或设置块。

WMIREG_FLAG_EXPENSIVE

请求 WMI 在数据使用者首次打开数据块时发送 IRP_MN_ENABLE_COLLECTION 请求，并在最后一个数据使用者关闭数据块时发送 IRP_MN_DISABLE_COLLECTION 请求。如果收集此类数据会影响性能，则建议这样做，因为驱动程序不需要收集数据，直到数据使用者通过打开块显式请求它。

WMIREG_FLAG_REMOVE_GUID

请求 WMI 删除对块的支持。此标志仅在响应将 Parameters.WMI.DataPath 设置为 WMIUPDATE) 的情况下， (IRP_MN_REGINFO或 IRP_MN_REGINFO_EX更新注册信息的请求时有效。

[out] InstanceName

指向单个计数 Unicode 字符串的指针，该字符串用作驱动程序要注册的所有块的所有实例的基名称。 WMI 使用 ExFreePool 释放字符串。如果清除WMIREG_FLAG_INSTANCE_BASENAME，则忽略 InstanceName 。

[out] RegistryPath

指向计数 Unicode 字符串的指针的指针，该字符串指定传递给驱动程序 DriverEntry 例程的注册表路径。

[out] MofResourceName

指向单个计数 Unicode 字符串的指针，该字符串指示附加到驱动程序的二进制映像文件的 MOF 资源的名称。通常，此字符串是驱动程序定义的静态字符串。在驱动程序从此例程返回后，WMI 会创建此字符串的副本。此字符串可由驱动程序动态分配。对于已分配的字符串，驱动程序负责释放应在 WmiSystemControl 返回后完成的字符串。如果驱动程序未附加 MOF 资源，它可以保留 MofResourceName 不变。

[out] Pdo

指向物理设备对象的指针 (PDO) 传递给驱动程序的 AddDevice 例程。如果设置了WMIREG_FLAG_INSTANCE_PDO，WMI 将使用此 PDO 的设备实例路径作为生成静态实例名称的基础。如果WMIREG_FLAG_INSTANCE_PDO清除，WMI 将忽略 Pdo。

返回值

DpWmiQueryReginfo 始终返回STATUS_SUCCESS。

注解

WMI 在驱动程序调用 WmiSystemControl 以响应IRP_MN_REGINFO或IRP_MN_REGINFO_EX请求后调用驱动程序的 DpWmiQueryReginfo 例程。驱动程序必须将其 DpWmiQueryReginfo 例程的地址放置在传递给 WmiSystemControl的WMILIB_CONTEXT结构中。

在驱动程序使用 WMIREG_ACTION_REGISTER、WMIREG_ACTION_REREGISTER 或 WMIREG_ACTION_UPDATE 调用 IoWMIRegistrationControl 后，WMI 发送 IRP。 WMI 代表驱动程序以透明方式处理 IRP_MN_REGINFO 和 IRP_MN_REGINFO_EX 之间的差异。

驱动程序使用 WMIREG_ACTION_DEREGISTER 调用 IoWMIRegistrationControl 后，WMI 不会发送IRP_MN_REGINFO或IRP_MN_REGINFO_EX请求，因为 WMI 不需要驱动程序提供进一步的信息。驱动程序通常会取消注册其块以响应 IRP_MN_REMOVE_DEVICE 请求。

驱动程序在传递给 WmiSystemControl的WMILIB_CONTEXT结构中提供有关各个块的新的或更新的注册信息，或指示要删除的块。在初始调用（这将建立驱动程序的注册表路径和 MOF 资源名称）之后，驱动程序的 DpWmiQueryReginfo 例程可以更改所有驱动程序块通用的标志，提供用于生成实例名称的不同基名称字符串，或者将实例名称的基础从字符串更改为 PDO 的设备实例路径。

驱动程序不得返回STATUS_PENDING或阻止请求。驱动程序不得通过从其 DpWmiQueryReginfo 例程调用 WmiCompleteRequest 或在 WmiSystemControl 返回后调用 IoCompleteRequest 来完成请求。

此例程可以分页。

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