WMI_QUERY_DATABLOCK_CALLBACK callback function (wmilib.h)

Article
10/21/2021

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

Syntax

WMI_QUERY_DATABLOCK_CALLBACK WmiQueryDatablockCallback;

NTSTATUS WmiQueryDatablockCallback(
  [in]      PDEVICE_OBJECT DeviceObject,
  [in]      PIRP Irp,
  [in]      ULONG GuidIndex,
  [in]      ULONG InstanceIndex,
  [in]      ULONG InstanceCount,
  [in, out] PULONG InstanceLengthArray,
  [in]      ULONG BufferAvail,
  [out]     PUCHAR Buffer
)
{...}

Parameters

[in] DeviceObject

Pointer to the driver's WDM DEVICE_OBJECT structure.

[in] Irp

Pointer to the IRP.

[in] GuidIndex

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.

[in] InstanceIndex

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.

[in] InstanceCount

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.

[in, out] InstanceLengthArray

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.

[in] BufferAvail

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.

[out] Buffer

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:

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

Requirement	Value
Target Platform	Desktop
Header	wmilib.h (include Wmilib.h)
IRQL	Called at PASSIVE_LEVEL.