Hardware Dev Center

EvtWmiProviderFunctionControl function

[Applies to KMDF only]

A driver's EvtWmiProviderFunctionControl callback function enables and disables the driver's support for collecting data and sending events for a specified WMI data provider.

Syntax


EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL EvtWmiProviderFunctionControl;

NTSTATUS EvtWmiProviderFunctionControl(
  _In_ WDFWMIPROVIDER           WmiProvider,
  _In_ WDF_WMI_PROVIDER_CONTROL Control,
  _In_ BOOLEAN                  Enable
)
{ ... }

Parameters

WmiProvider [in]

A handle to a WMI provider object.

Control [in]

A WDF_WMI_PROVIDER_CONTROL-typed value that identifies a capability that the driver must enable or disable.

Enable [in]

A Boolean value that, if TRUE, indicates that the driver must enable the capability that Control specifies. If FALSE, the driver must disable the capability.

Return value

The EvtWmiProviderFunctionControl callback function must return STATUS_SUCCESS if the operation succeeds. Otherwise, it must return a status value for which NT_SUCCESS(status) equals FALSE.

Remarks

To register an EvtWmiProviderFunctionControl callback function, your driver must place the function's address in a WDF_WMI_PROVIDER_CONFIG structure before it calls WdfWmiProviderCreate.

If your driver sets the WdfWmiProviderExpensive flag in the Flags member of a WMI data provider's WDF_WMI_PROVIDER_CONFIG structure, and if the driver provides an EvtWmiProviderFunctionControl callback function, the framework calls the callback function when the driver should enable or disable its ability to collect WMI data.

Instead of providing an EvtWmiProviderFunctionControl callback function, the driver can call WdfWmiProviderIsEnabled to find out if it should enable or disable collecting data.

For more information about the EvtWmiProviderFunctionControl callback function, see Supporting WMI in Framework-Based Drivers.

Examples

To define an EvtWmiProviderFunctionControl callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtWmiProviderFunctionControl callback function that is named MyWmiProviderFunctionControl, use the EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL type as shown in this code example:

To define an EvtWmiProviderFunctionControl callback function that is named MyWmiProviderFunctionControl, you must first provide a function declaration that SDV and other verification tools require, as follows:


EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL  MyWmiProviderFunctionControl;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyWmiProviderFunctionControl (
    WDFWMIPROVIDER  WmiProvider,
    WDF_WMI_PROVIDER_CONTROL  Control,
    BOOLEAN  Enable
    )
  {...}

The EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL function type is defined in the WdfWMI.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Header

WdfWMI.h (include Wdf.h)

IRQL

PASSIVE_LEVEL

See also

EvtWmiInstanceQueryInstance
EvtWmiInstanceSetInstance
EvtWmiInstanceSetItem
EvtWmiInstanceExecuteMethod
WDF_WMI_PROVIDER_CONFIG
WDF_WMI_PROVIDER_CONTROL
WdfWmiProviderCreate
WdfWmiProviderIsEnabled

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft