Función IoOpenDeviceRegistryKey (wdm.h)

Artículo
08/08/2023

La rutina IoOpenDeviceRegistryKey devuelve un identificador a una ubicación de estado del Registro para una instancia de dispositivo determinada.

Sintaxis

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

Parámetros

[in] DeviceObject

Puntero al objeto de dispositivo físico (PDO) de la instancia de dispositivo para la que se va a abrir la ubicación del estado del Registro.

[in] DevInstKeyType

Especifica marcas que indican si se debe abrir una clave de hardware específica del dispositivo o una clave de software específica del controlador. Las marcas también indican si la clave es relativa al perfil de hardware actual. Para obtener más información sobre las claves de hardware y software, consulte Introducción a las claves del Registro para controladores.

Las marcas se definen de la siguiente manera:

PLUGPLAY_REGKEY_DEVICE

Abra la clave de hardware del dispositivo, una ubicación de estado del Registro específica del dispositivo que contiene información sobre el dispositivo. Esta marca no se puede especificar con PLUGPLAY_REGKEY_DRIVER.

PLUGPLAY_REGKEY_DRIVER

Abra la clave de software del dispositivo, una ubicación de estado del Registro específica del dispositivo para almacenar información específica del controlador. Esta marca no se puede especificar con PLUGPLAY_REGKEY_DEVICE.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Los perfiles de hardware están en desuso y el estado no se debe almacenar en relación con un perfil de hardware.

Abra una clave relativa al perfil de hardware actual para la información del dispositivo o del controlador. Esto permite al controlador acceder a la información de configuración específica del perfil de hardware. El autor de la llamada debe especificar PLUGPLAY_REGKEY_DEVICE o PLUGPLAY_REGKEY_DRIVER con esta marca.

[in] DesiredAccess

Especifica el valor de ACCESS_MASK que representa el acceso que el autor de la llamada necesita a la clave. Consulte la rutina ZwCreateKey para obtener una descripción de cada derecho de acceso KEY_XXX .

[out] DeviceRegKey

Puntero a un búfer asignado por el autor de la llamada que, al devolverse correctamente, contiene un identificador para la ubicación de estado del Registro solicitada.

Valor devuelto

IoOpenDeviceRegistryKey devuelve STATUS_SUCCESS si la llamada se realizó correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Posiblemente indica que el autor de la llamada especificó un conjunto no válido de marcas DevInstKeyType o proporcionó un DeviceObject que no es un PDO válido.

Comentarios

El controlador debe llamar a ZwClose para cerrar el identificador devuelto de esta rutina cuando el acceso ya no es necesario.

Las claves del Registro abiertas por esta rutina no son volátiles.

Las aplicaciones de configuración en modo de usuario pueden acceder a estas claves del Registro mediante CM_Open_DevNode_Key o funciones de información del dispositivo , como SetupDiOpenDevRegKey o SetupDiCreateDevRegKey.

Para rellenar previamente el estado en estas ubicaciones de estado del Registro en el momento de la instalación del paquete de controladores, use las directivas AddReg inf en un archivo INF.

Los autores de llamadas de IoOpenDeviceRegistryKey deben ejecutarse en IRQL = PASSIVE_LEVEL en el contexto de un subproceso del sistema.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)