WMI_FUNCTION_CONTROL_CALLBACK回呼函式（wmilib.h）

發行項
02/07/2025

DpWmiFunctionControl 例程會啟用或停用事件的通知，並啟用或停用驅動程式註冊為昂貴收集之數據區塊的數據收集。此例程是選擇性的。

語法

WMI_FUNCTION_CONTROL_CALLBACK WmiFunctionControlCallback;

NTSTATUS WmiFunctionControlCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] WMIENABLEDISABLECONTROL Function,
  [in] BOOLEAN Enable
)
{...}

參數

[in] DeviceObject

驅動程式的 WDM DEVICE_OBJECT 結構的指標。

[in] Irp

IRP 的指標。

[in] GuidIndex

藉由將以零起始的索引提供給驅動程式在傳遞至 WmiSystemControl WMILIB_CONTEXT 結構中提供的 GUID 清單，指定數據區塊。

[in] Function

指定要啟用或停用的內容。 WmiEventControl 表示事件，WmiDataBlockControl 表示註冊為昂貴之區塊的數據收集（也就是驅動程式在旗標中設定WMIREG_FLAG_EXPENSIVE的區塊，WMIGUIDREGINFO 結構用來註冊區塊）。

[in] Enable

指定 TRUE 來啟用事件或數據收集，或 FALSE 停用它。

傳回值

DpWmiFunctionControl 會傳回STATUS_SUCCESS或適當的錯誤狀態，例如：

言論

WMI 會在驅動程式呼叫 WmiSystemControl 以回應下列其中一個要求之後，呼叫驅動程式的 DpWmiFunctionControl 例程：

IRP_MN_ENABLE_COLLECTION

IRP_MN_DISABLE_COLLECTION

IRP_MN_ENABLE_EVENTS

IRP_MN_DISABLE_EVENTS

如果驅動程式實作 DpWmiFunctionControl 例程，驅動程式必須將例程的位址放在 WmiFunctionControlWMILIB_CONTEXT 結構的成員，而該 WmiSystemControl。如果驅動程式未實作 DpWmiFunctionControl 例程，則必須將 WmiFunctionControl 設定為 NULL。在後者的情況下，WMI 會將STATUS_SUCCESS傳回給呼叫端。

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

根據 WMILIB_CONTEXT 結構的 GuidCount 成員，確認 GuidIndex 值介於零和 GuidCount-1 之間。
確認驅動程式尚未標示要移除的指定數據區塊。如果驅動程式最近在 WMIGUIDREGINFO 中指定WMIREG_FLAG_REMOVE_GUID旗標，結構中包含的 WMILIB_CONTEXT 結構，則移除發生之前，可能會有其他要求到達。

驅動程式不需要檢查是否已經為區塊啟用事件或數據收集，因為 WMI 會在第一個數據取用者啟用區塊時傳送單一啟用要求，並在最後一個數據取用者停用區塊時傳送單一停用要求。 WMI 不會呼叫 DpWmiFunctionControl 來啟用區塊，而不需介入呼叫來停用它。

啟用或停用區塊的事件或數據收集之後，驅動程式會呼叫 WmiCompleteRequest 來完成要求。

這個例程可以分頁。

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