IRP_MN_QUERY_SINGLE_INSTANCE

项目
06/15/2023

所有支持 WMI 的驱动程序都必须处理此 IRP。驱动程序可以通过调用 WmiSystemControl 或通过处理 IRP 本身来处理 WMI IRP，如处理 WMI 请求中所述。

如果驱动程序调用 WmiSystemControl 来处理 IRP_MN_QUERY_SINGLE_INSTANCE 请求，则 WMI 又调用该驱动程序的 DpWmiQueryDataBlock 例程。

主代码

发送时

WMI 发送此 IRP 以查询给定数据块的单个实例。

WMI 在发送 IRP_MN_EXECUTE_METHOD 之前发送 IRP_MN_QUERY_SINGLE_INSTANCE。如果驱动程序支持 IRP_MN_EXECUTE_METHOD，则它必须为正在执行其方法的相同数据块具有 IRP_MN_QUERY_SINGLE_INSTANCE 处理程序。

WMI 在 IRQL = PASSIVE_LEVEL任意线程上下文中发送此 IRP。

输入参数

Parameters.WMI.ProviderId 指向应响应请求的驱动程序的设备对象。此指针位于 IRP 中驱动程序的 I/O 堆栈位置。

Parameters.WMI.DataPath 指向标识要查询的数据块的 GUID。

Parameters.WMI.BufferSize 指示 Parameters.WMI.Buffer 的非分页缓冲区的最大大小，该缓冲区指向标识要查询的实例 的WNODE_SINGLE_INSTANCE 结构。

输出参数

如果驱动程序通过调用 WmiSystemControl 处理 WMI IRP，则 WMI 使用驱动程序的 DpWmiQueryDataBlock 例程提供的数据填充WNODE_SINGLE_INSTANCE结构。

否则，驱动程序会在 Parameters.WMI.Buffer 处填充WNODE_SINGLE_INSTANCE结构，如下所示：

汇报 WnodeHeader.BufferSize，其输出WNODE_SINGLE_INSTANCE结构（包括实例数据）的大小（以字节为单位）。此值应包括填充 (实例名称的长度，以便实例数据从四个字边界) 开始，即使正在查询的类注册了静态实例名称，并且驱动程序编写器在为此 IRP 提供服务时未显式提供名称。
将 SizeDataBlock 设置为实例数据的大小（以字节为单位）。如果使用静态实例名称，则此值不应包含实例名称的大小。
从 DataBlockOffset 开始，将实例数据写入 Parameters.WMI.Buffer。驱动程序不得更改 DataBlockOffset 的输入值。

如果 Parameters.WMI.Buffer 中的缓冲区太小，无法接收所有数据，驱动程序会在 Parameters.WMI.Buffer的WNODE_TOO_SMALL结构中填充所需的大小。如果 缓冲区小于 (WNODE_TOO_SMALL) 的大小，驱动程序将失败 IRP 并返回STATUS_BUFFER_TOO_SMALL。

I/O 状态块

如果驱动程序通过调用 WmiSystemControl 处理 IRP，则 WMI 在 I/O 状态块中设置 Irp-IoStatus.Status> 和 Irp-IoStatus.Information>。

否则，驱动程序会将 Irp-IoStatus.Status> 设置为STATUS_SUCCESS或相应的错误状态，如下所示：

STATUS_BUFFER_TOO_SMALL

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_INSTANCE_NOT_FOUND

成功后，驱动程序会将 Irp-IoStatus.Information> 设置为在 WnodeHeader.BufferSize 中输入的值。此值包括静态实例名称的长度。

Operation

驱动程序可以通过调用 WmiSystemControl 或通过处理 IRP 本身来处理 WMI IRP，如处理 WMI 请求中所述。

如果驱动程序通过调用 WmiSystemControl 处理 WMI IRP， 则 WmiSystemControl 将调用驱动程序的 DpWmiQueryDataBlock 例程。

如果驱动程序处理 IRP_MN_QUERY_SINGLE_INSTANCE 请求本身，则仅当 Parameters.WMI.ProviderId 指向与驱动程序在 调用 IoWMIRegistrationControl 时传递的指针相同的设备对象时，它才应执行此操作。否则，驱动程序必须将请求转发到设备堆栈中的下一个较低驱动程序。

在处理请求之前，驱动程序必须确定 Parameters.WMI.DataPath 是否指向驱动程序支持的 GUID。否则，驱动程序必须使 IRP 失败并返回STATUS_WMI_GUID_NOT_FOUND。

驱动程序负责验证所有输入值。具体而言，如果驱动程序处理 IRP 请求本身，则必须执行以下操作：

对于静态名称，请验证 WNODE_SINGLE_INSTANCE 结构的 InstanceIndex 成员是否在数据块驱动程序支持的实例索引范围内。
对于动态名称，请验证实例名称字符串是否标识驱动程序支持的数据块实例。
验证 Parameters.WMI.BufferSize 指定的缓冲区是否足够大，可以接收驱动程序将返回的所有数据。

如果驱动程序支持数据块，它会在 Parameters.WMI.Buffer 处检查输入WNODE_SINGLE_INSTANCE实例名称，如下所示：

如果在 WnodeHeader.Flags 中设置了WNODE_FLAG_STATIC_INSTANCE_NAMES，则驱动程序使用 InstanceIndex 作为该块的驱动程序静态实例名称列表中的索引。 WMI 在注册块时从驱动程序提供的注册数据中获取索引。
如果在 WnodeHeader.Flags 中清除WNODE_FLAG_STATIC_INSTANCE_NAMES，则驱动程序使用 OffsetInstanceName 中的偏移量在输入 WNODE_SINGLE_INSTANCE中找到实例名称字符串。 OffsetInstanceName 是结构开头到 USHORT 的偏移量（以字节为单位），它是实例名称字符串的长度（以字节 (而不是字符) ，包括终止 null（如果存在），后跟 Unicode 中的实例名称字符串。

如果驱动程序找不到指定的实例，则必须使 IRP 失败并返回STATUS_WMI_INSTANCE_NOT_FOUND。对于具有动态实例名称的实例，此状态指示驱动程序不支持该实例。因此，WMI 可以继续查询其他数据访问接口，如果另一个提供程序找到该实例，但由于其他原因而无法处理请求，则向数据使用者返回相应的错误。

如果驱动程序找到实例并可以处理请求，则会使用实例的数据填充 Parameters.WMI.Buffer 中的WNODE_SINGLE_INSTANCE结构。

如果实例有效，但驱动程序无法处理请求，它可以返回任何适当的错误状态。