IRP_MN_CHANGE_SINGLE_ITEM
All drivers that support WMI must handle this IRP. A driver can handle WMI IRPs either by calling WmiSystemControl or by handling the IRP itself, as described in Handling WMI Requests.
If a driver calls WmiSystemControl to handle an IRP_MN_CHANGE_SINGLE_ITEM request, WMI in turn calls that driver's DpWmiSetDataItem routine.
Major Code
When Sent
WMI sends this IRP to change a single data item in a single instance of a data block.
WMI sends this IRP at IRQL = PASSIVE_LEVEL in an arbitrary thread context.
Input Parameters
Parameters.WMI.ProviderId points to the device object of the driver that should respond to the request. This pointer is located in the driver's I/O stack location in the IRP.
Parameters.WMI.DataPath points to a GUID that identifies the data block to be set.
Parameters.WMI.BufferSize indicates the size of the nonpaged buffer at Parameters.WMI.Buffer.
Parameters.WMI.Buffer, points to a WNODE_SINGLE_ITEM structure that identifies the instance of the data block, the ID of the item to set, and a new data value.
Output Parameters
None.
I/O Status Block
If the driver handles the IRP by calling WmiSystemControl, WMI sets Irp->IoStatus.Status and Irp->IoStatus.Information in the I/O status block.
Otherwise, the driver sets Irp->IoStatus.Status to STATUS_SUCCESS or to an appropriate error status such as the following:
STATUS_WMI_INSTANCE_NOT_FOUND
STATUS_WMI_ITEMID_NOT_FOUND
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_READ_ONLY
STATUS_WMI_SET_FAILURE
On success, a driver sets Irp->IoStatus.Information to zero.
Operation
If a driver handles WMI IRPs by calling WmiSystemControl, that routine calls the driver's DpWmiSetDataItem routine, or returns STATUS_WMI_READ_ONLY if the driver does not define the routine.
If a driver handles IRP_MN_CHANGE_SINGLE_ITEM requests itself, it should do so only if Parameters.WMI.ProviderId points to the same device object as the pointer that the driver passed to IoWMIRegistrationControl. Otherwise, the driver must forward the request to the next-lower driver.
Do not implement support for IRP_MN_CHANGE_SINGLE_ITEM unless you are sure that a system-supplied user-mode component requires this capability.
Before handling a request, the driver must determine whether Parameters.WMI.DataPath points to a GUID that the driver supports. If it does not, the driver must fail the IRP and return STATUS_WMI_GUID_NOT_FOUND.
If the driver supports the data block, it must check the input WNODE_SINGLE_ITEM structure that Parameters.WMI.Buffer points to for the instance name, as follows:
If WNODE_FLAG_STATIC_INSTANCE_NAMES is set in WnodeHeader.Flags, the driver uses InstanceIndex as an index into the driver's list of static instance names for that block. WMI obtains the index from registration data provided by the driver when it registered the block.
If WNODE_FLAG_STATIC_INSTANCE_NAMES is clear in WnodeHeader.Flags, the driver uses the offset at OffsetInstanceName to locate the instance name string in the input WNODE_SINGLE_ITEM structure. OffsetInstanceName is the offset in bytes from the beginning of the structure to a USHORT-sized length of the instance name string in bytes (not characters). This length includes the NULL terminator if present, followed by the instance name string in Unicode.
The driver is responsible for validating all input values. Specifically, the driver must do the following if it handles the IRP request itself:
For static names, verify that the InstanceIndex member of the WNODE_SINGLE_ITEM structure is within the range of instance indexes supported by the driver for the data block.
For dynamic names, verify that the instance name string identifies a data block instance supported by the driver.
Verify that the ItemId member of the WNODE_SINGLE_ITEM structure is within the range of item identifiers supported by the driver for the data block.
Verify that the DataBlockOffset and SizeDataItem members of the WNODE_SINGLE_ITEM structure describe a valid-sized data block, and that the contents of the buffer are valid for the data item.
Verify that the specified data item is one for which the driver allows caller-initiated modifications. In other words, the driver should not allow modifications to data items that you intended to be read-only.
Do not assume the thread context is that of the initiating user-mode application—a higher-level driver might have changed it.
If the driver cannot locate the specified instance, it must fail the IRP and return STATUS_WMI_INSTANCE_NOT_FOUND. For an instance with a dynamic instance name, this status indicates that the driver does not support the instance. WMI can therefore continue to query other data providers, and return an appropriate error to the data consumer if another provider finds the instance but cannot handle the request for some other reason.
If the driver locates the instance and can handle the request, it sets the data item in the instance to the value in the WNODE_SINGLE_ITEM. If the data item is read-only, the driver leaves the item unchanged, fails the IRP, and returns STATUS_WMI_READ_ONLY.
If the instance is valid but the driver cannot handle the request, it can return any appropriate error status.
Requirements
Header |
Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h) |