共用方式為

WMI_QUERY_DATABLOCK_CALLBACK回呼函式 （wmilib.h）

  • 發行項

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

提供呼叫端的指標，InstanceCountULONG 元素的大小陣列。 驅動程式會填入每個數位元素，以指出所傳回之每個實例的長度。 如果 BufferAvail 為零，InstanceLengthArrayNULL。

[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 值介於零和 GuidCount-1 之間。
  • 確認驅動程式尚未標示要移除的指定數據區塊。 如果驅動程式最近在 WMIGUIDREGINFO 中指定了WMIREG_FLAG_REMOVE_GUID旗標， 結構 WMILIB_CONTEXT 中包含的結構，則查詢在移除發生之前可能會到達。
  • 確認 InstanceIndex 和 InstanceCount 值，同時指定數據區塊驅動程式所支援範圍內的多個數據區塊實例。 如果 InstanceIndex 為非零，InstanceCount 必須是 1。 如果 InstanceIndex 為 0，InstanceCount 不得大於支援的實例數目。
  • 確認 Buffer 和 BufferAvail 所描述的緩衝區夠大，足以保存數據區塊的所有要求實例。 每個實例都必須在8位元組界限上開始，而且每個實例內的數據項之間可能會有額外的填補。
將實例數據寫入緩衝區之後，驅動程式會呼叫 WmiCompleteRequest 來完成要求。 如果 Buffer 和 BufferAvail 所描述的緩衝區為零，或太小而無法接收所有要求的數據，則 呼叫 wmiCompleteRequest 必須指定 Status 參數的STATUS_BUFFER_TOO_SMALL，以及 BufferUsed 參數所需的緩衝區大小。

這個例程可以分頁。

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

要求

要求 價值
目標平臺 桌面
標頭 wmilib.h （包括 Wmilib.h）
IRQL 在 PASSIVE_LEVEL呼叫。

另請參閱

IRP_MN_QUERY_ALL_DATA

IRP_MN_QUERY_SINGLE_INSTANCE

WMILIB_CONTEXT

WmiCompleteRequest

WmiSystemControl