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。可能的错误返回值包括：

返回代码	说明
STATUS_INVALID_PARAMETER	可能指示调用方指定了一组非法的 DevInstKeyType 标志，或者提供了不是有效 PDO 的 DeviceObject 。

注解

当不再需要访问时，驱动程序必须调用 ZwClose 以关闭从此例程返回的句柄。

此例程打开的注册表项是非易失性注册表项。

用户模式安装应用程序可以使用 CM_Open_DevNode_Key 或设备信息函数（如 SetupDiOpenDevRegKey 或 SetupDiCreateDevRegKey）访问这些注册表项。

若要在驱动程序包安装时在这些注册表状态位置中预先填充状态，请在 INF 文件中使用 INF AddReg 指令。

IoOpenDeviceRegistryKey 的调用方必须在系统线程上下文中的 IRQL = PASSIVE_LEVEL 运行。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (请参阅“备注”部分)
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， PowerIrpDDis (wdm)