Edit

Share via

WMI_FUNCTION_CONTROL_CALLBACK callback function (wmilib.h)

  • Article

The DpWmiFunctionControl routine enables or disables notification of events, and enables or disables data collection for data blocks that the driver registered as expensive to collect. This routine is optional.

Syntax

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

Parameters

[in] DeviceObject

Pointer to the driver's WDM DEVICE_OBJECT structure.

[in] Irp

Pointer to the IRP.

[in] GuidIndex

Specifies the data block by supplying a zero-based index into the list of GUIDs that the driver provided in the WMILIB_CONTEXT structure it passed to WmiSystemControl.

[in] Function

Specifies what to enable or disable. WmiEventControl indicates an event, and WmiDataBlockControl indicates data collection for a block that was registered as expensive to collect (that is, a block for which the driver set WMIREG_FLAG_EXPENSIVE in Flags of the WMIGUIDREGINFO structure used to register the block).

[in] Enable

Specifies TRUE to enable the event or data collection, or FALSE to disable it.

Return value

DpWmiFunctionControl returns STATUS_SUCCESS or an appropriate error status such as:

Remarks

WMI calls a driver's DpWmiFunctionControl routine after the driver calls WmiSystemControl in response to one of the following requests:

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

If a driver implements a DpWmiFunctionControl routine, the driver must place the routine's address in the WmiFunctionControl member of the WMILIB_CONTEXT structure that it passes to WmiSystemControl. If a driver does not implement a DpWmiFunctionControl routine, it must set WmiFunctionControl to NULL. In the latter case, WMI returns STATUS_SUCCESS to the caller.

The driver is responsible for validating all input arguments. Specifically, the driver must do the following:

  • Verify that the GuidIndex value is between zero and GuidCount-1, based on the GuidCount member of the WMILIB_CONTEXT structure.
  • Verify that the driver has not flagged the specified data block for removal. If the driver recently specified the WMIREG_FLAG_REMOVE_GUID flag in a WMIGUIDREGINFO structure that is contained in a WMILIB_CONTEXT structure, it is possible for an additional request to arrive before the removal occurs.
It is unnecessary for the driver to check whether events or data collection are already enabled for a block, because WMI sends a single enable request when the first data consumer enables the block, and it sends a single disable request when the last data consumer disables the block. WMI will not call DpWmiFunctionControl to enable a block without an intervening call to disable it.

After enabling or disabling the event or data collection for the block, the driver calls WmiCompleteRequest to complete the request.

This routine can be pageable.

For more information about implementing this routine, see Calling WmiSystemControl to Handle WMI IRPs.

Requirements

Requirement Value
Target Platform Desktop
Header wmilib.h (include Wmilib.h)
IRQL Called at PASSIVE_LEVEL.

See also

IRP_MN_DISABLE_COLLECTION

IRP_MN_DISABLE_EVENTS

IRP_MN_ENABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

WMILIB_CONTEXT

WmiSystemControl