EvtWmiInstanceSetInstance function

[Applies to KMDF only]

A driver's EvtWmiInstanceSetInstance callback function sets all of a WMI data provider's instance data to values that a WMI client supplies.

Syntax


EVT_WDF_WMI_INSTANCE_SET_INSTANCE EvtWmiInstanceSetInstance;

NTSTATUS EvtWmiInstanceSetInstance(
  _In_ WDFWMIINSTANCE WmiInstance,
  _In_ ULONG          InBufferSize,
  _In_ PVOID          InBuffer
)
{ ... }

Parameters

WmiInstance [in]

A handle to a WMI instance object.

InBufferSize [in]

The size, in bytes, of the input buffer that InBuffer points to.

InBuffer [in]

A pointer to the input buffer.

Return value

The EvtWmiInstanceSetInstance callback function must return STATUS_SUCCESS if the operation succeeds. Otherwise, this function must return a status value for which NT_SUCCESS(status) equals FALSE. If the input buffer that the InBuffer parameter points to is too small to contain all of the data that the driver expects, the callback function must return STATUS_WMI_SET_FAILURE.

Remarks

To register an EvtWmiInstanceSetInstance callback function, your driver must place the function's address in a WDF_WMI_INSTANCE_CONFIG structure before calling WdfWmiInstanceCreate.

The framework does not synchronize calls to a driver's WMI event callback functions with each other or with any of the driver's other event callback functions. If an EvtWmiInstanceSetInstance callback function's data is dynamic and shared with other callback functions, your driver can use the framework's wait locks or spin locks to synchronize access to the data.

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

Examples

To define an EvtWmiInstanceSetInstance 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 EvtWmiInstanceSetInstance callback function that is named MyWmiInstanceSetInstance, use the EVT_WDF_WMI_INSTANCE_SET_INSTANCE type as shown in this code example:

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


EVT_WDF_WMI_INSTANCE_SET_INSTANCE  MyWmiInstanceSetInstance;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyWmiInstanceSetInstance (
    WDFWMIINSTANCE  WmiInstance,
    ULONG  InBufferSize,
    PVOID  InBuffer
    )
  {...}

The EVT_WDF_WMI_INSTANCE_SET_INSTANCE 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_INSTANCE_SET_INSTANCE 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
EvtWmiInstanceSetItem
EvtWmiInstanceExecuteMethod
EvtWmiProviderFunctionControl
WDF_WMI_INSTANCE_CONFIG
WdfWmiInstanceCreate

 

 

Send comments about this topic to Microsoft

Afficher:
© 2015 Microsoft