WMI_QUERY_DATABLOCK_CALLBACK回呼函式 (wmilib.h)

發行項
02/27/2024

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 例程。驅動程式必須在傳遞給 WmiSystemControl 的 WMILIB_CONTEXT 結構中放置其 DpWmiQueryDataBlock 例程的位址。

驅動程式負責驗證所有輸入自變數。具體而言，驅動程式必須執行下列動作：

根據 WMILIB_CONTEXT 結構的 GuidCount 成員，確認 GuidIndex 值介於零和 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 參數和 BufferUsed 參數的必要緩衝區大小指定STATUS_BUFFER_TOO_SMALL。

此例程可以分頁。

如需實作此例程的詳細資訊，請參閱呼叫 WmiSystemControl 來處理 WMI IRP。