WMI_FUNCTION_CONTROL_CALLBACK回呼函式 (wmilib.h)

發行項
02/27/2024

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 表示註冊 (為昂貴區塊的數據收集，也就是驅動程式在用來註冊區塊) 之 WMIGUIDREGINFO 結構旗標中設定WMIREG_FLAG_EXPENSIVE的區塊。

[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 例程，驅動程式必須將例程的位址放在傳遞給 WmiSystemControl 之WMILIB_CONTEXT結構的 WmiFunctionControl 成員中。如果驅動程式未實作 DpWmiFunctionControl 例程，則必須將 WmiFunctionControl 設定為 NULL。在後者的情況下，WMI 會將STATUS_SUCCESS傳回給呼叫端。

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

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

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

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

此例程可以分頁。

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