IRP_MN_ENABLE_COLLECTION

Article
03/01/2023

Any WMI driver that registers one or more of its data blocks as potentially time-consuming, or expensive, to collect 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_ENABLE_COLLECTION request, WMI in turn calls that driver's DpWmiFunctionControl routine.

Major Code

IRP_MJ_SYSTEM_CONTROL

When Sent

WMI sends this IRP to request the driver to start accumulating data for a data block that the driver registered as expensive to collect.

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 for which data is accumulated.

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_GUID_NOT_FOUND

STATUS_INVALID_DEVICE_REQUEST

On success, a driver sets Irp->IoStatus.Information to zero.

Operation

A driver registers a data block as expensive to collect by setting WMIREG_FLAG_EXPENSIVE in the Flags member of the WMIREGGUID or WMIGUIDREGINFO structure. The driver passes these structures to WMI when it registers or updates the data block. A driver need not accumulate data for such a block until it receives an explicit request to start data collection.

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 handles WMI IRPs by calling WmiSystemControl, that routine calls the driver's DpWmiFunctionControl routine, or returns STATUS_SUCCESS if the driver does not define the routine.

If a driver handles an IRP_MN_ENABLE_COLLECTION request 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.

Before handling a request, the driver should make sure that Parameters.WMI.DataPath points to a GUID that the driver supports. If it does not, the driver should fail the IRP and return STATUS_WMI_GUID_NOT_FOUND. If the data block is valid but was not registered with WMIREG_FLAG_EXPENSIVE, the driver can return STATUS_SUCCESS and take no further action.

If the block is valid and was registered with WMIREG_FLAG_EXPENSIVE, the driver enables data collection for all instances of that data block.

It is unnecessary for the driver to check whether data collection is already enabled for the data block. WMI sends only a single request to enable a data block after the first data consumer enables the block. WMI will not send another request to enable without an intervening disable request.

Requirements

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)