IRP_MN_CHANGE_SINGLE_INSTANCE

项目
06/15/2023

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

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

主代码

IRP_MJ_SYSTEM_CONTROL

发送时

WMI 发送此 IRP 以更改数据块的单个实例中的所有数据项。

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

输入参数

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

Parameters.WMI.DataPath 指向一个 GUID，该 GUID 标识与要更改的实例关联的数据块。

Parameters.WMI.BufferSize 指示 Parameters.WMI.Buffer 中非分页缓冲区的大小。

Parameters.WMI.Buffer 指向标识实例并指定新数据值的 WNODE_SINGLE_INSTANCE 结构。

输出参数

无。

I/O 状态块

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

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

STATUS_WMI_INSTANCE_NOT_FOUND

STATUS_WMI_GUID_NOT_FOUND

STATUS_WMI_READ_ONLY

STATUS_WMI_SET_FAILURE

成功后，驱动程序会将 Irp-IoStatus.Information> 设置为零。

Operation

如果驱动程序通过调用 WmiSystemControl 处理 WMI IRP，则该例程将调用驱动程序的 DpWmiSetDataBlock 例程，如果驱动程序未定义例程，则返回STATUS_WMI_READ_ONLY。

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

如果驱动程序处理请求，则必须先在 Parameters.WMI.DataPath 检查 GUID，以确定它是否标识驱动程序支持的数据块。否则，驱动程序必须使 IRP 失败并返回STATUS_WMI_GUID_NOT_FOUND。

如果驱动程序支持数据块，则必须在 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 请求本身，则必须执行以下操作：

对于静态名称，请验证 WNODE_SINGLE_INSTANCE 结构的 InstanceIndex 成员是否在数据块驱动程序支持的实例索引范围内。
对于动态名称，请验证实例名称字符串是否标识驱动程序支持的数据块实例。
验证 WNODE_SINGLE_INSTANCE 结构的 DataBlockOffset 和 SizeDataBlock 成员是否描述有效大小的数据块，包括数据项之间存在的任何填充，以及缓冲区的内容是否对数据块有效。
验证指定的数据块是否是驱动程序允许调用方发起的修改的数据块。换句话说，驱动程序不应允许修改你打算为只读的数据块。

不要假设线程上下文是发起的用户模式应用程序的上下文，更高级别的驱动程序可能已更改它。

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

如果驱动程序找到实例并可以处理请求，则会将实例中的可写数据项设置为 WNODE_SINGLE_INSTANCE 结构中的值，使任何只读项保持不变。如果整个数据块是只读的，则驱动程序应使 IRP 失败并返回STATUS_WMI_READ_ONLY。

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