Función WdfRegistryOpenKey (wdfregistry.h)

Artículo
03/22/2025

[Se aplica a KMDF y UMDF]

El método WdfRegistryOpenKey abre una clave del Registro especificada y crea un objeto de clave del Registro de marco que representa la clave del Registro.

Sintaxis

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parámetros

[in, optional] ParentKey

Identificador de un objeto de clave del Registro de marco. Este objeto representa una clave del Registro primaria que el controlador ha abierto. Este parámetro es opcional y se puede NULL. Si el parámetro no está null, la clave que KeyName especifica debe residir bajo esta clave primaria en el Registro. Para obtener más información sobre esta clave primaria, vea la sección Comentarios.

[in] KeyName

Puntero a una estructura UNICODE_STRING que contiene el nombre de la clave que se va a abrir. El nombre de clave puede incluir información de ruta de acceso. Si ParentKey es null, KeyName debe especificar una ruta de acceso completa a una clave del Registro. Para obtener ejemplos, vea la sección Comentarios.

[in] DesiredAccess

Valor de tipo ACCESS_MASKque especifica los derechos de acceso que solicita el controlador para la clave del Registro especificada. Para obtener una lista de los derechos de acceso que los controladores suelen usar para las claves del Registro, vea Abrir un identificador en un objeto Registry-Key. El controlador debe solicitar solo los tipos de acceso que necesita. Por ejemplo, el controlador no debe solicitar KEY_ALL_ACCESS si solo leerá la clave del Registro.

[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

WdfRegistryOpenKey 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 de retorno	Descripción
STATUS_INVALID_DEVICE_REQUEST	no se llamó a WdfRegistryOpenKey en IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Se especificó un parámetro no válido.
STATUS_INSUFFICIENT_RESOURCES	No se pudo asignar un objeto de clave del Registro.
STATUS_ACCESS_DENIED	El sistema denegó los derechos de acceso especificados.
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 WdfRegistryOpenKey, consulte Errores de creación de objetos de marco.

Este método también puede devolver otros valores de NTSTATUS.

Observaciones

Para obtener un identificador de un objeto de clave del Registro que representa una clave primaria, el controlador puede llamar a WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKeyo WdfFdoInitOpenRegistryKey.

El formato de cadena especificado en el parámetro keyName depende de si el autor de la llamada es un controlador KMDF o un controlador UMDF. Por ejemplo, para abrir la ruta de acceso siguiente:

HKLM\System\CurrentControlSet\Control

El controlador puede usar esta lógica condicional:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

Cuando el controlador ha terminado de usar una clave del Registro que se abre con WdfRegistryOpenKey, el controlador debe llamar a WdfRegistryClose.

Para obtener más información sobre los objetos de clave del Registro, vea Using the Registry in Framework-Based Drivers.

Ejemplos

En el ejemplo de código siguiente se abre la clave de software de un controlador y, a continuación, se abre el MySubKey clave del Registro, que se encuentra bajo la clave de software del controlador.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

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	wdfregistry.h (incluya Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)