Función WdfDeviceOpenRegistryKey (wdfdevice.h)

Artículo
02/07/2025

[Se aplica a KMDF y UMDF]

El método WdfDeviceOpenRegistryKey abre la clave de hardware de un dispositivo o la clave de software de un controlador en el Registro y crea un objeto de clave del Registro de marco que representa la clave del Registro.

Sintaxis

NTSTATUS WdfDeviceOpenRegistryKey(
  [in]           WDFDEVICE              Device,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] DeviceInstanceKeyType

Especifica qué clave o subclave se va a abrir.

Nota

UMDF no admite la creación de subclaves.

Se trata de un OR bit a bit de las marcas siguientes (que se definen en Wdm.h).

Marca DeviceInstanceKeyType	Significado	Marco de referencia
PLUGPLAY_REGKEY_DEVICE	Abre la clave de hardware del dispositivo.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Abre la clave de software del controlador. Un controlador UMDF que establece esta marca también debe establecer DesiredAccess en KEY_READ. De lo contrario, este método devuelve STATUS_ACCESS_DENIED.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Un controlador KMDF usa esta marca para abrir la copia de la clave de hardware o software que se encuentra en el perfil de hardware actual.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Un controlador UMDF usa estas marcas juntas para abrir el ServiceName subclave de la clave de software del controlador para el acceso de lectura y escritura.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Del mismo modo, un controlador UMDF usa estas marcas para abrir la subclave ServiceName de la clave de hardware del dispositivo para el acceso de lectura y escritura.	UMDF

[in] DesiredAccess

Valor de tipo ACCESS_MASKque especifica los derechos de acceso que solicita el controlador para la clave del Registro especificada.

Normalmente, un controlador KMDF solicita KEY_READ, KEY_WRITEo KEY_READ | KEY_WRITE.

Si va a escribir un controlador UMDF, use la tabla siguiente.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ o KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ o KEY_READ \| KEY_SET_VALUE

Como procedimiento recomendado, solicite solo los tipos de acceso que necesita el controlador.

[in, optional] KeyAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES que contiene atributos proporcionados por el controlador para el nuevo objeto de clave del Registro. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[out] Key

Puntero a una ubicación que recibe un identificador del nuevo objeto de clave del Registro.

Valor devuelto

WdfDeviceOpenRegistryKey devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	no se llamó a WdfDeviceOpenRegistryKey en IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido. Para UMDF, este valor devuelto puede indicar derechos de acceso insuficientes.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un objeto de clave del Registro.
STATUS_OBJECT_NAME_NOT_FOUND	La clave del Registro especificada no existe.

Para obtener una lista de otros valores devueltos que el método WdfDeviceOpenRegistryKey podría devolver, consulte Errores de creación de objetos de marco.

El método podría devolver otros valores ntstatus de .

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Observaciones

Si el controlador debe abrir una clave de hardware o software antes de llamar a WdfDeviceCreate, debe llamar a WdfFdoInitOpenRegistryKey en lugar de WdfDeviceOpenRegistryKey.

Cuando el controlador haya terminado de usar la clave del Registro que abrió con WdfDeviceOpenRegistryKey, el controlador debe llamar a WdfRegistryClose.

Para obtener más información sobre el registro, las claves de hardware y software y los objetos del Registro, consulte Using the Registry in Framework-Based Drivers.

Ejemplos

Para obtener ejemplos de código que usan WdfDeviceOpenRegistryKey, vea WdfRegistryCreateKey, WdfRegistryOpenKeyy WdfRegistryQueryValue.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
versión mínima de UMDF	2.0
encabezado de	wdfdevice.h (incluya Wdf.h)
biblioteca de	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte también

WdfFdoInitOpenRegistryKey

Compartir a través de