WMI_QUERY_DATABLOCK_CALLBACK回调函数 (wmilib.h)

项目
08/08/2023

DpWmiQueryDataBlock 例程返回数据块的单个实例或所有实例。此例程是必需的。

语法

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
)
{...}

参数

[in] DeviceObject

指向驱动程序的 WDM DEVICE_OBJECT 结构的指针。

[in] Irp

指向 IRP 的指针。

[in] GuidIndex

通过将从零开始的索引提供给驱动程序在传递给 WmiSystemControl 的 WMILIB_CONTEXT 结构中提供的 GUID 列表中来指定数据块。

[in] InstanceIndex

如果调用 DpWmiQueryDataBlock 以响应 IRP_MN_QUERY_SINGLE_INSTANCE 请求， 则 InstanceIndex 将指定一个从零开始的索引，该索引指示要查询的指定数据块的实例。如果调用 DpWmiQueryDataBlock 以响应 IRP_MN_QUERY_ALL_DATA 请求， 则 InstanceIndex 为零。

[in] InstanceCount

如果调用 DpWmiQueryDataBlock 以响应 IRP_MN_QUERY_SINGLE_INSTANCE 请求， 则 InstanceCount 为 1。如果调用 DpWmiQueryDataBlock 以响应 IRP_MN_QUERY_ALL_DATA 请求， 则 InstanceCount 是要返回的实例数。

[in, out] InstanceLengthArray

指向调用方提供的 、InstanceCount 大小的 ULONG 元素数组的指针。驱动程序填充每个数组元素，以指示返回的每个实例的长度。如果 BufferAvail 为零， 则 InstanceLengthArray 为 NULL。

[in] BufferAvail

指定 缓冲区中可用于接收缓冲区中数据的最大字节数。如果此值为零，则调用方请求驱动程序在调用 WmiCompleteRequest 时指定所需的缓冲区大小。有关详细信息，请参阅备注部分。

[out] Buffer

指向用于接收实例数据的缓冲区的指针。如果缓冲区足够大，可以接收所有数据，驱动程序会将实例数据写入缓冲区，每个实例在 8 字节边界上对齐。如果缓冲区太小而无法接收所有数据，驱动程序将调用 WmiCompleteRequest ，并将 BufferUsed 设置为所需的大小。

返回值

DpWmiQueryDataBlock 返回STATUS_SUCCESS或错误状态，如下所示：

如果驱动程序无法立即完成请求，它可以返回STATUS_PENDING。

注解

WMI 在驱动程序调用 WmiSystemControl 以响应IRP_MN_QUERY_SINGLE_INSTANCE或IRP_MN_QUERY_ALL_DATA请求后调用驱动程序的 DpWmiQueryDataBlock 例程。驱动程序必须将 DpWmiQueryDataBlock 例程的地址放在传递给 WmiSystemControl的WMILIB_CONTEXT结构中。

驱动程序负责验证所有输入参数。具体而言，驱动程序必须执行以下操作：

根据 WMILIB_CONTEXT 结构的 GuidCount 成员，验证 GuidIndex 值是否介于 0 和 GuidCount-1 之间。
验证驱动程序是否未标记要删除的指定数据块。如果驱动程序最近在 WMILIB_CONTEXT 结构中包含的 WMIGUIDREGINFO 结构中指定 了WMIREG_FLAG_REMOVE_GUID 标志，则查询可能在删除发生之前到达。
验证 InstanceIndex 和 InstanceCount 值一起指定数据块驱动程序支持范围内的多个数据块实例。如果 InstanceIndex 不为零， 则 InstanceCount 必须为 1。如果 InstanceIndex 为 0， 则 InstanceCount 不得大于支持的实例数。
验证 Buffer 和 BufferAvail 描述的缓冲区是否足够大，足以容纳数据块的所有请求实例。每个实例必须从 8 字节边界开始，并且每个实例中的数据项之间可能存在额外的填充。

将实例数据写入缓冲区后，驱动程序会调用 WmiCompleteRequest 来完成请求。如果 Buffer 和BufferAvail 描述的缓冲区为零，或者太小而无法接收所有请求的数据，则对 WmiCompleteRequest 的 调用必须为 Status 参数指定STATUS_BUFFER_TOO_SMALL，并为 BufferUsed 参数指定所需的缓冲区大小。

此例程可以分页。

有关实现此例程的详细信息，请参阅调用 WmiSystemControl 以处理 WMI IRP。