Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

DpWmiFunctionControl routine

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


NTSTATUS DpWmiFunctionControl(
  _In_ PDEVICE_OBJECT          DeviceObject,
  _In_ PIRP                    Irp,
  _In_ ULONG                   GuidIndex,
  _In_ WMIENABLEDISABLECONTROL Function,
  _In_ BOOLEAN                 Enable
);

Parameters

DeviceObject [in]

Pointer to the driver's WDM DEVICE_OBJECT structure.

Irp [in]

Pointer to the IRP.

GuidIndex [in]

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.

Function [in]

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).

Enable [in]

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:

STATUS_WMI_GUID_NOT_FOUND
STATUS_INVALID_DEVICE_REQUEST

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

Target platform

Desktop

Header

Wmilib.h (include Wmilib.h)

IRQL

Called at PASSIVE_LEVEL.

See also

IRP_MN_ENABLE_COLLECTION
IRP_MN_DISABLE_COLLECTION
IRP_MN_ENABLE_EVENTS
IRP_MN_DISABLE_EVENTS
WMILIB_CONTEXT
WmiSystemControl

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft