DpWmiQueryDataBlock routine

The DpWmiQueryDataBlock routine returns either a single instance or all instances of a data block. This routine is required.

Syntax


NTSTATUS DpWmiQueryDataBlock(
  _In_    PDEVICE_OBJECT DeviceObject,
  _In_    PIRP           Irp,
  _In_    ULONG          GuidIndex,
  _In_    ULONG          InstanceIndex,
  _In_    ULONG          InstanceCount,
  _Inout_ PULONG         InstanceLengthArray,
  _In_    ULONG          BufferAvail,
  _Out_   PUCHAR         Buffer
);

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.

InstanceIndex [in]

If DpWmiQueryDataBlock is called in response to an IRP_MN_QUERY_SINGLE_INSTANCE request, InstanceIndex specifies a zero-based index that indicates the instance of the specified data block to be queried. If DpWmiQueryDataBlock is called in response to an IRP_MN_QUERY_ALL_DATA request, InstanceIndex is zero.

InstanceCount [in]

If DpWmiQueryDataBlock is called in response to an IRP_MN_QUERY_SINGLE_INSTANCE request, InstanceCount is 1. If DpWmiQueryDataBlock is called in response to an IRP_MN_QUERY_ALL_DATA request, InstanceCount is the number of instances to be returned.

InstanceLengthArray [in, out]

Pointer to a caller-supplied, InstanceCount-sized array of ULONG elements. The driver fills in each array element to indicate the length of each instance that was returned. If BufferAvail is zero, InstanceLengthArray is NULL.

BufferAvail [in]

Specifies the maximum number of bytes that are available to receive data in the buffer at Buffer. If this value is zero, the caller is requesting that the driver specify the required buffer size in its call to WmiCompleteRequest. See the Remarks section for more information.

Buffer [out]

Pointer to the buffer to receive instance data. If the buffer is large enough to receive all of the data, the driver writes the instance data to the buffer with each instance aligned on an 8-byte boundary. If the buffer is too small to receive all of the data, the driver calls WmiCompleteRequest with BufferUsed set to the size required.

Return value

DpWmiQueryDataBlock returns STATUS_SUCCESS or an error status such as the following:

STATUS_BUFFER_TOO_SMALL
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_INSTANCE_NOT_FOUND

If the driver cannot complete the request immediately, it can return STATUS_PENDING.

Remarks

WMI calls a driver's DpWmiQueryDataBlock routine after the driver calls WmiSystemControl in response to an IRP_MN_QUERY_SINGLE_INSTANCE or IRP_MN_QUERY_ALL_DATA request. The driver must place the address of its DpWmiQueryDataBlock routine in the WMILIB_CONTEXT structure that it passes to WmiSystemControl.

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 a query to arrive before the removal occurs.

  • Verify that the InstanceIndex and InstanceCount values, together, specify a number of data block instances that is within the range supported by the driver for the data block. If InstanceIndex is nonzero, InstanceCount must be 1. If InstanceIndex is 0, InstanceCount must not be greater than the number of instances supported.

  • Verify that the buffer described by Buffer and BufferAvail is large enough to hold all requested instances of the data block. Each instance must begin on an 8-byte boundary, and additional padding might exist between data items within each instance.

After writing instance data to the buffer, the driver calls WmiCompleteRequest to complete the request. If the buffer described by Buffer and BufferAvail is zero, or is too small to receive all the requested data, the call to WmiCompleteRequest must specify STATUS_BUFFER_TOO_SMALL for the Status parameter and the required buffer size for the BufferUsed parameter.

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_QUERY_ALL_DATA
IRP_MN_QUERY_SINGLE_INSTANCE
WMILIB_CONTEXT
WmiCompleteRequest
WmiSystemControl

 

 

Send comments about this topic to Microsoft

Show: