Edit

Share via

Sending an Event with IoWMIWriteEvent

  • Article

A driver can call IoWMIWriteEvent to send any event. The event can consist of a single item, a single instance, or all instances of a data block, and it can use dynamic instance names.

Unlike WNODE_XXX structures passed with query or change requests, which are allocated and partially initialized by WMI, the driver must allocate and initialize all members of the WNODE_XXX structure that contains an event.

A driver must send an event only after WMI has sent an IRP_MN_ENABLE_EVENTS request to enable the event. Then, when the event's trigger condition occurs, the driver:

  1. Allocates a buffer from nonpaged pool to contain the WNODE_XXX structure needed for the event, including space for variable data, if any.

    Depending on the event, the driver might allocate a WNODE_SINGLE_ITEM, a WNODE_SINGLE_INSTANCE, or a WNODE_ALL_DATA for the event. The size of the WNODE_XXX plus variable data must not exceed the registry-defined limit of 1K.

  2. Initializes all members of the WNODE_XXX structure, including WnodeHeader.Flags:

    • The driver sets the WNODE_FLAG_EVENT_ITEM flag to indicate that the structure is an event.

    • The driver sets one of the following flags to indicate the type of WNODE_XXX structure:

      WNODE_FLAG_ALL_DATA

      WNODE_FLAG_SINGLE_INSTANCE

      WNODE_FLAG_SINGLE_ITEM

    • The driver sets or clears the following flags to indicate whether the block uses static or dynamic instance names:

      WNODE_FLAG_STATIC_INSTANCE_NAMES

      WNODE_FLAG_PDO_INSTANCE_NAMES

    • The driver might set additional flags depending on the event.

  3. Casts a pointer to the WNODE_XXX to a PWNODE_EVENT_ITEM.

  4. Calls IoWMIWriteEvent with the pointer.

    If IoWMIWriteEvent completes successfully, WMI releases the driver-allocated memory for the event.

After IoWMIWriteEvent returns, the driver resumes monitoring the event's trigger condition and sending the event each time its trigger condition occurs, until WMI sends an IRP_MN_DISABLE_EVENTS request to disable that event.

If the size of an event exceeds the registry-defined maximum of 1K (not recommended) the driver should call IoWmiWriteEvent with an initialized WNODE_EVENT_REFERENCE that specifies the event's GUID, its size, and its instance index (for static instance names) or name (for dynamic instance names). WMI will use the information in the WNODE_EVENT_REFERENCE to query for the event.

A driver can send an events that does not use dynamic instance names and that consists of a single instance by calling the WMI library routine WmiFireEvent. The driver does not need to allocate and initialize a WNODE_XXX structure for a WmiFireEvent call. WMI packages the driver's event data in a WNODE_SINGLE_INSTANCE and delivers it to data consumers. For more information about sending events with WmiFireEvent, see Sending an Event with WmiFireEvent.