EvtWmiInstanceExecuteMethod function

[Applies to KMDF only]

A driver's EvtWmiInstanceExecuteMethod callback function executes a specified method that the driver provides for a WMI data provider's instance.

Syntax


EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD EvtWmiInstanceExecuteMethod;

NTSTATUS EvtWmiInstanceExecuteMethod(
  _In_     WDFWMIINSTANCE WmiInstance,
  _In_     ULONG MethodId,
  _In_     ULONG InBufferSize,
  _In_     ULONG OutBufferSize,
  _Inout_  PVOID Buffer,
  _Out_    PULONG BufferUsed
)
{ ... }

Parameters

WmiInstance [in]

A handle to a WMI instance object.

MethodId [in]

A value that identifies a method in a provider instance. This value corresponds to the WmiMethodId value that is specified in the provider's MOF file.

InBufferSize [in]

The number of bytes of input data.

OutBufferSize [in]

The number of bytes of output data that the buffer that Buffer points to can hold.

Buffer [in, out]

A pointer to a buffer that is used for input, output, or both, as determined by the specified method. If both input and output data are provided, the driver overwrites the input data with the output data.

BufferUsed [out]

A pointer to a location that receives the number of bytes that the driver wrote into the output buffer. If the output buffer size that the OutBufferSize parameter specifies is too small, the driver sets this location to the required buffer size.

Return value

The EvtWmiInstanceExecuteMethod 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. The driver must return STATUS_BUFFER_TOO_SMALL if the value of the OutBufferSize parameter indicates that the output buffer is too small to receive the data.

Remarks

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

After a driver executes the instance method that the MethodId parameter specifies, the driver must use the BufferUsed parameter to store the number of bytes that were written to the buffer.

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 EvtWmiInstanceExecuteMethod 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 EvtWmiInstanceExecuteMethod callback function, see Supporting WMI in Framework-Based Drivers.

Examples

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

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


EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD  MyWmiInstanceExecuteMethod;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyWmiInstanceExecuteMethod (
    WDFWMIINSTANCE  WmiInstance,
    ULONG  MethodId,
    ULONG  InBufferSize,
    ULONG  OutBufferSize,
    PVOID  Buffer,
    PULONG  BufferUsed
    )
  {...}

The EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD 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_EXECUTE_METHOD 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

Minimum KMDF version

1.0

Header

WdfWMI.h (include Wdf.h)

IRQL

PASSIVE_LEVEL

See also

EvtWmiInstanceQueryInstance
EvtWmiInstanceSetInstance
EvtWmiInstanceSetItem
EvtWmiProviderFunctionControl
WDF_WMI_INSTANCE_CONFIG
WdfWmiInstanceCreate

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft