WMI_QUERY_REGINFO_CALLBACK回呼函式 (wmilib.h)

發行項
02/27/2024

DpWmiQueryReginfo 例程提供驅動程式要註冊的數據區塊和事件區塊的相關信息。此例程是必要的。

語法

WMI_QUERY_REGINFO_CALLBACK WmiQueryReginfoCallback;

NTSTATUS WmiQueryReginfoCallback(
  [in]  PDEVICE_OBJECT DeviceObject,
  [out] PULONG RegFlags,
  [out] PUNICODE_STRING InstanceName,
  [out] PUNICODE_STRING *RegistryPath,
  [out] PUNICODE_STRING MofResourceName,
  [out] PDEVICE_OBJECT *Pdo
)
{...}

參數

[in] DeviceObject

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

[out] RegFlags

此參數表示所有已註冊區塊的通用特性。 RegFlags 中設定的任何旗標都會套用至所有區塊。驅動程式可以在區塊的 WMIGUIDREGINFO 結構中設定 Flags，來補充指定區塊的 RegFlags。例如，驅動程式可能會在 RegFlags 中清除WMIREG_FLAG_EXPENSIVE，但在 Flags 中將其設定為將指定的區塊註冊為成本高昂的收集。

驅動程式會在 RegFlags 中設定下列其中一個旗標：

WMIREG_FLAG_INSTANCE_BASENAME

要求 WMI 從驅動程式在 InstanceName 提供的基底名稱產生靜態實例名稱。 WMI 會將計數器附加至基底名稱，以產生實例名稱。

WMIREG_FLAG_INSTANCE_PDO

要求 WMI 從 PDO 的裝置實例標識碼產生靜態實例名稱。如果驅動程式設定此旗標，它也必須將 Pdo 設定為傳遞給驅動程式 AddDevice 例程的 PDO。 WMI 會從 PDO 的裝置實例路徑產生實例名稱。使用裝置實例路徑作為靜態實例名稱的基底是有效率的，因為這類名稱保證是唯一的。 WMI 會自動提供實例的「易記」名稱，做為數據取用者可查詢之數據區塊中的專案。

驅動程式也可能在 RegFlags 中設定下列一或多個旗標，但通常會在區塊 WMIGUIDREGINFO 結構的旗標中設定這些旗標：

WMIREG_FLAG_EVENT_ONLY_GUID

區塊只能啟用或停用為事件，而且無法查詢或設定。如果這個旗標清楚，也可以查詢或設定區塊。

WMIREG_FLAG_EXPENSIVE

要求 WMI 在第一次數據取用者開啟數據區塊時傳送 IRP_MN_ENABLE_COLLECTION 要求，並在最後一個數據取用者關閉數據區塊時提出IRP_MN_DISABLE_COLLECTION 要求。如果收集這類數據會影響效能，建議這麼做，因為驅動程式必須等到數據取用者藉由開啟區塊明確要求數據之後，才需要收集數據。

WMIREG_FLAG_REMOVE_GUID

要求 WMI 移除區塊的支援。此旗標只有在回應要求以更新註冊資訊 (IRP_MN_REGINFO 或 IRP_MN_REGINFO_EX參數.WMI.DataPath 設定為 WMIUPDATE) 時才有效。

[out] InstanceName

單一已計算 Unicode 字串的指標，可作為驅動程式所註冊之所有區塊之所有實例的基底名稱。 WMI 會使用 ExFreePool 釋放字串。如果WMIREG_FLAG_INSTANCE_BASENAME清楚， 則會忽略 InstanceName 。

[out] RegistryPath

指向計數 Unicode 字串指標的指標，指定傳遞至驅動程式 DriverEntry 例程的登錄路徑。

[out] MofResourceName

單一計數 Unicode 字串的指標，表示附加至驅動程式二進位圖像檔之 MOF 資源的名稱。此字串通常是驅動程式所定義的靜態。 WMI 會在驅動程式從這個例程傳回之後，製作此字串的複本。此字串可由驅動程序動態配置。如果是已配置的字串，驅動程式會負責釋放應該在 WmiSystemControl 傳回之後完成的字串。如果驅動程式沒有附加MOF資源，它可以讓 MofResourceName 保持不變。

[out] Pdo

實體裝置物件的指標， (PDO) 傳遞給驅動程式的 AddDevice 例程。如果設定WMIREG_FLAG_INSTANCE_PDO，WMI 會使用此 PDO 的裝置實例路徑做為基底，以產生靜態實例名稱。如果WMIREG_FLAG_INSTANCE_PDO清楚，WMI 會忽略 Pdo。

傳回值

DpWmiQueryReginfo 一律會傳回STATUS_SUCCESS。

備註

WMI 會在驅動程式呼叫 WmiSystemControl 以回應IRP_MN_REGINFO或IRP_MN_REGINFO_EX要求之後呼叫驅動程式的 DpWmiQueryReginfo 例程。驅動程式必須在傳遞給 WmiSystemControl的 WMILIB_CONTEXT 結構中放置其 DpWmiQueryReginfo 例程的位址。

WMI 會在驅動程式呼叫 IoWMIRegistrationControl 並搭配 WMIREG_ACTION_REGISTER、WMIREG_ACTION_REREGISTER 或 WMIREG_ACTION_UPDATE 呼叫 IoWMIRegistrationControl 之後傳送 IRP。 WMI 會以透明方式代表驅動程序處理 IRP_MN_REGINFO 與 IRP_MN_REGINFO_EX 之間的差異。

WMI 不會在驅動程式呼叫 IoWMIRegistrationControl 與 WMIREG_ACTION_DEREGISTER 之後傳送IRP_MN_REGINFO或IRP_MN_REGINFO_EX要求，因為 WMI 不需要驅動程式的進一步資訊。驅動程式通常會取消註冊其區塊，以回應 IRP_MN_REMOVE_DEVICE 要求。

驅動程式會提供個別區塊的新或更新註冊資訊，或指出要移除的區塊，在它傳遞給 WmiSystemControl的WMILIB_CONTEXT結構中。初始呼叫之後，它會建立驅動程式的登錄路徑和MOF資源名稱，驅動程式的 DpWmiQueryReginfo 例程可以變更所有驅動程式區塊通用的旗標、提供用來產生實例名稱的不同基底名稱字元串，或將實例名稱的基礎從字元串變更為 PDO 的裝置實例路徑。

驅動程式不得傳回STATUS_PENDING或封鎖要求。驅動程式不得從其 DpWmiQueryReginfo 例程呼叫 WmiCompleteRequest，或在 WmiSystemControl 傳回之後呼叫 IoCompleteRequest 來完成要求。

此例程可以分頁。

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