IRP_MN_ENABLE_EVENTS

Article
03/01/2023

Any WMI driver that registers one or more event blocks 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_EVENTS request, WMI in turn calls that driver's DpWmiFunctionControl routine.

Major Code

IRP_MJ_SYSTEM_CONTROL

When Sent

WMI sends this IRP to inform the driver that a data consumer has requested notification of an event.

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 event block to enable.

Parameters.WMI.BufferSize indicates the size of the nonpaged buffer at Parameters.WMI.Buffer, which must be greater than or equal to the sizeof(WNODE_HEADER). A driver that does not register trace blocks (WMIREG_FLAG_TRACED_GUID) can ignore this parameter.

Parameters.WMI.Buffer points to a WNODE_HEADER that indicates whether the event should be traced (WMI_FLAGS_TRACED_GUID) and provides a handle to the system logger. A driver that does not register trace blocks (WMIREG_FLAG_TRACED_GUID) can ignore this parameter.

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 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_EVENTS 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 the driver handles the request, it should determine whether Parameters.WMI.DataPath points to a GUID that the driver supports. If not, the driver must fail the IRP and return STATUS_WMI_GUID_NOT_FOUND.

If the driver supports the event block, it enables the event for all instances of that data block.

It is unnecessary for the driver to check whether events are already enabled for the event block because WMI sends a single request to enable for the event block when the first data consumer enables the event. WMI will not send another request to enable without an intervening disable request.

A driver that registers trace blocks (WMIREG_FLAG_TRACED_GUID) must also determine whether to send the event to WMI or to the system logger for tracing. If tracing is requested, Parameters.WMI.Buffer points to a WNODE_HEADER structure in which Flags is set with WNODE_FLAG_TRACED_GUID and HistoricalContext contains a handle to the logger.

For details about defining event blocks, sending events, and tracing, see Windows Management Instrumentation.

Requirements

Header

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