Función WdfDeviceOpenRegistryKey (wdfdevice.h)

  • Artículo

[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 la clave o subclave que 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
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 DesiredAccessen 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 la subclave ServiceName de la clave de software del controlador para el acceso de lectura y escritura. UMDF
PLUGPLAY_REGKEY_DEVICE | WDF_REGKEY_DEVICE_SUBKEY De forma similar, 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 ACCESS_MASK con tipo que especifica los derechos de acceso que el controlador solicita para la clave del Registro especificada.

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

Si está escribiendo 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 para el 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 podría devolver el método WdfDeviceOpenRegistryKey , vea Errores de creación de objetos de marco.

El método podría devolver otros valores NTSTATUS.

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

Comentarios

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, vea Uso del Registro en controladores de Framework-Based.

Ejemplos

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

Requisitos

Requisito Value
Plataforma de destino Universal
Versión mínima de KMDF 1.0
Versión mínima de UMDF 2.0
Encabezado wdfdevice.h (incluya Wdf.h)
Library 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