EvtWmiInstanceQueryInstance function

[Applies to KMDF only]

A driver's EvtWmiInstanceQueryInstance callback function copies a WMI provider's instance data into a buffer for delivery to a WMI client.

Syntax


EVT_WDF_WMI_INSTANCE_QUERY_INSTANCE EvtWmiInstanceQueryInstance;

NTSTATUS EvtWmiInstanceQueryInstance(
  _In_   WDFWMIINSTANCE WmiInstance,
  _In_   ULONG OutBufferSize,
  _In_   PVOID OutBuffer,
  _Out_  PULONG BufferUsed
)
{ ... }

Parameters

WmiInstance [in]

A handle to a WMI instance object.

OutBufferSize [in]

The size, in bytes, of the output buffer that OutBuffer points to.

OutBuffer [in]

A pointer to the output buffer.

BufferUsed [out]

A pointer to a location that receives the number of bytes that the driver places in 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 EvtWmiInstanceQueryInstance callback function 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. Otherwise, the callback function must copy data into the buffer and return STATUS_SUCCESS.

Remarks

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

Before the framework sends the driver-supplied instance data to the WMI client, it adds all of the necessary WMI header information to the data.

If your driver sets the UseContextForQuery member of the WMI instance object's WDF_WMI_INSTANCE_CONFIG structure to TRUE for a read-only data block, the driver does not provide an EvtWmiInstanceQueryInstance callback function.

If your driver must provide string data to a WMI client, the driver should call the WDF_WMI_BUFFER_APPEND_STRING function to format the string.

For more information about the EvtWmiInstanceQueryInstance callback function, see Supporting Read/Write WMI Data Blocks and Supporting Read-Only WMI Data Blocks.

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

Examples

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

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


EVT_WDF_WMI_INSTANCE_QUERY_INSTANCE  MyWmiInstanceQueryInstance;

Then, implement your callback function as follows:


_Use_decl_annotations_
NTSTATUS
 MyWmiInstanceQueryInstance (
    WDFWMIINSTANCE  WmiInstance,
    ULONG  OutBufferSize,
    PVOID  OutBuffer,
    PULONG  BufferUsed
    )
  {...}

The EVT_WDF_WMI_INSTANCE_QUERY_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_QUERY_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

Minimum KMDF version

1.0

Header

WdfWMI.h (include Wdf.h)

IRQL

PASSIVE_LEVEL

See also

EvtWmiInstanceSetInstance
EvtWmiInstanceSetItem
EvtWmiInstanceExecuteMethod
EvtWmiProviderFunctionControl
WDF_WMI_BUFFER_APPEND_STRING
WDF_WMI_INSTANCE_CONFIG
WdfWmiInstanceCreate

 

 

Send comments about this topic to Microsoft

Afficher:
© 2014 Microsoft