Función WdfRegistryCreateKey (wdfregistry.h)
[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 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.
[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] CreateOptions
Una o varias 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 se puede NULL.
[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
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 de retorno | Descripción |
|---|---|
|
no se llamó a WdfRegistryCreateKey en IRQL = PASSIVE_LEVEL. |
|
Se especificó un parámetro no válido. |
|
No se pudo asignar un objeto de clave del Registro. |
|
El sistema denegó los derechos de acceso especificados. |
|
La clave del Registro especificada no existe. |
Para obtener una lista de otros valores devueltos que el método WdfRegistryCreateKey podría devolver, vea Framework Object Creation Errors.
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.
De forma predeterminada, el nuevo objeto primario de clave del Registro es el objeto de controlador de marco que crea el WdfDriverCreate método. Puede usar el miembro parentObject de de la estructura WDF_OBJECT_ATTRIBUTES para especificar un elemento primario diferente. 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 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 crea y se abre el myKeyStr 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"myKeyStr"
);
status = WdfRegistryCreateKey(
hKey,
&myKeyStr,
KEY_READ,
REG_OPTION_NON_VOLATILE,
NULL,
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) |