Función WdfRegistryCreateKey (wdfregistry.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

El método WdfRegistryCreateKey crea y abre una clave del Registro especificada, o simplemente abre la clave si ya existe y crea un objeto de clave del Registro de marco que representa la clave del Registro.

Sintaxis

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [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 puede ser NULL. Si el parámetro no es NULL, la clave que Especifica KeyName 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.

[in] DesiredAccess

Valor con tipo ACCESS_MASK que 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, consulte Apertura de un identificador a 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] CreateOptions

Una o más marcas. Para obtener información sobre estas marcas, vea el parámetro CreateOptions o ZwCreateKey.

[out, optional] CreateDisposition

Puntero a una ubicación que recibe REG_CREATED_NEW_KEY si se crea una nueva clave o REG_OPENED_EXISTING_KEY si se abre una clave existente. Estos valores se definen en Wdm.h. Este puntero es opcional y puede ser NULL.

[in, optional] KeyAttributes

Puntero a una estructura WDF_OBJECT_ATTRIBUTES que contiene atributos proporcionados por el controlador para el nuevo objeto de clave del Registro. Este parámetro es opcional y puede ser 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

WdfRegistryCreateKey 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 WdfRegistryCreateKey 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 puede devolver el método WdfRegistryCreateKey , vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Comentarios

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

De forma predeterminada, el nuevo objeto primario de clave del Registro es el objeto de controlador de marco que crea el método WdfDriverCreate . Puede usar el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES para especificar otro elemento primario. El marco elimina el objeto de clave del Registro cuando elimina el objeto primario. Si el controlador no cambia el elemento primario predeterminado, el controlador debe eliminar el objeto de clave del Registro cuando haya terminado de usar el objeto ; De lo contrario, el objeto de clave del Registro permanecerá hasta que el administrador de E/S descargue el controlador.

Si el controlador no cambia el elemento primario predeterminado, el controlador debe llamar a WdfRegistryClose cuando haya terminado de usar el objeto ; De lo contrario, el objeto de clave del Registro permanecerá hasta que el administrador de E/S descargue el controlador. Como alternativa, el controlador puede llamar a WdfObjectDelete para eliminar el objeto de clave del Registro.

Para obtener más información sobre los objetos de clave del Registro, vea Uso del Registro en controladores de Framework-Based.

Ejemplos

En el ejemplo de código siguiente se abre la clave de software de un controlador y, a continuación, se crea y se abre la clave del Registro myKeyStr , 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"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &subkey
                                  );
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfregistry.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)