IoOpenDeviceRegistryKey 函式 (wdm.h)

發行項
02/27/2024

IoOpenDeviceRegistryKey 例程會傳回特定裝置實例登錄狀態位置的句柄。

語法

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

參數

[in] DeviceObject

實體裝置物件的指標， ( 要開啟登錄狀態位置之裝置實例的 PDO) 。

[in] DevInstKeyType

指定旗標，指出是否要開啟裝置特定的硬體密鑰或驅動程式特定的軟體密鑰。旗標也會指出金鑰是否相對於目前的硬體配置檔。如需硬體和軟體密鑰的詳細資訊，請參閱驅動程式的登錄機碼簡介。

旗標的定義如下：

PLUGPLAY_REGKEY_DEVICE

開啟裝置的硬體密鑰，這是包含裝置相關信息的裝置特定登錄狀態位置。此旗標無法使用 PLUGPLAY_REGKEY_DRIVER來指定。

PLUGPLAY_REGKEY_DRIVER

開啟裝置的軟體密鑰，這是用來儲存驅動程式特定資訊的裝置特定登錄狀態位置。無法以 PLUGPLAY_REGKEY_DEVICE 指定這個旗標。

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

硬體配置檔已被取代，且不應將狀態儲存在相對於硬體配置檔。

開啟相對於目前硬體配置檔的金鑰，以取得裝置或驅動程序資訊。這可讓驅動程式存取硬體配置檔專屬的組態資訊。呼叫端必須使用這個旗標來指定PLUGPLAY_REGKEY_DEVICE或PLUGPLAY_REGKEY_DRIVER。

[in] DesiredAccess

指定 ACCESS_MASK 值，表示呼叫端對金鑰所需的存取。如需每個KEY_XXX 訪問許可權的描述，請參閱 ZwCreateKey 例程。

[out] DeviceRegKey

呼叫端配置緩衝區的指標，在成功傳回時，會包含所要求登錄狀態位置的句柄。

傳回值

如果呼叫成功，IoOpenDeviceRegistryKey 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括：

傳回碼	Description
STATUS_INVALID_PARAMETER	可能表示呼叫端指定了一組不合法的 DevInstKeyType 旗標，或提供不是有效 PDO 的 DeviceObject 。

備註

當不再需要存取時，驅動程式必須呼叫 ZwClose 以關閉從這個例程傳回的句柄。

此例程所開啟的登錄機碼為非volatile。

使用者模式設定應用程式可以使用 CM_Open_DevNode_Key 或裝置資訊功能來存取這些登錄機碼，例如 SetupDiOpenDevRegKey 或 SetupDiCreateDevRegKey。

若要在驅動程式套件安裝時間預先填入這些登錄狀態位置中的狀態，請在 INF 檔案中使用 INF AddReg 指示詞。

IoOpenDeviceRegistryKey 的呼叫端必須在 IRQL = PASSIVE_LEVEL系統線程的內容中執行。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅一节)
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)