Función ZwCreateKey (wdm.h)

Artículo
12/22/2024

La rutina ZwCreateKey crea una nueva clave del Registro o abre una existente.

Sintaxis

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parámetros

[out] KeyHandle

Puntero a una variable HANDLE que recibe un identificador de la clave.

[in] DesiredAccess

Especifica un valor de ACCESS_MASK que determina el acceso solicitado al objeto . Además de los derechos de acceso definidos para todos los tipos de objetos (vea ACCESS_MASK), el autor de la llamada puede especificar uno o varios de los siguientes derechos de acceso, que son específicos de los directorios de objetos:

Marca de DesiredAccess	Permite al autor de la llamada hacer esto
KEY_QUERY_VALUE	Lee los valores de clave.
KEY_SET_VALUE	Escribir valores de clave.
KEY_CREATE_SUB_KEY	Cree subclaves para la clave.
KEY_ENUMERATE_SUB_KEYS	Lea las subclaves de la clave.
KEY_CREATE_LINK	Cree un vínculo simbólico a la clave. Este indicador no lo usan los controladores intermedios y del dispositivo.
KEY_NOTIFY	Pida que reciba una notificación cuando cambie el nombre, el valor o los atributos de la clave. Para obtener más información, vea ZwNotifyChangeKey.

El autor de la llamada también puede especificar una de las siguientes constantes, que combina varias marcas de ACCESS_MASK.

Constante	Consta de estas marcas de ACCESS_MASK
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS y KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE y KEY_CREATE_SUB_KEY
KEY_EXECUTE	Igual que KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY y KEY_CREATE_LINK

[in] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use InitializeObjectAttributes para inicializar esta estructura. Si el autor de la llamada no se ejecuta en un contexto de subproceso del sistema, debe establecer el atributo OBJ_KERNEL_HANDLE cuando llama a InitializeObjectAttributes.

TitleIndex

Los controladores intermedios y de dispositivo establecen este parámetro en cero.

[in, optional] Class

Puntero a una cadena Unicode que contiene la clase de objeto de la clave. El administrador de configuración usa esta información.

[in] CreateOptions

Especifica las opciones que se aplicarán al crear o abrir una clave, especificadas como una combinación compatible de las marcas siguientes.

Marca de CreateOptions	Descripción
REG_OPTION_VOLATILE	La clave no se conserva cuando se reinicia el sistema.
REG_OPTION_NON_VOLATILE	La clave se conserva cuando se reinicia el sistema.
REG_OPTION_CREATE_LINK	La clave recién creada es un vínculo simbólico. Este indicador no lo usan los controladores intermedios y del dispositivo.
REG_OPTION_BACKUP_RESTORE	La clave debe crearse o abrirse con privilegios especiales que permitan las operaciones de copia de seguridad y restauración. Este indicador no lo usan los controladores intermedios y del dispositivo.

[out, optional] Disposition

Puntero a una variable que recibe un valor que indica si se creó una nueva clave o una existente abierta.

valor de eliminación	Descripción
REG_CREATED_NEW_KEY	Se creó una nueva clave.
REG_OPENED_EXISTING_KEY	Se abrió una clave existente.

Valor devuelto

ZwCreateKey devuelve STATUS_SUCCESS correcto o el código de error NTSTATUS adecuado en caso de error.

Observaciones

ZwCreateKey proporciona un identificador que el autor de la llamada puede usar para manipular una clave del Registro. Para obtener más información, vea Using the Registry in a Driver.

Una vez que el controlador al que apunta KeyHandle ya no está en uso, el controlador debe llamar a ZwClose para cerrarlo.

Hay dos maneras alternativas de especificar el nombre del archivo que se va a crear o abrir con ZwCreateKey:

Como nombre de ruta de acceso completo, proporcionado en el ObjectName miembro de la entrada ObjectAttributes. Los nombres de ruta de acceso de las claves del Registro comienzan por \Registry.
Como pathname con respecto a otra clave del Registro, representada por el identificador en el miembro RootDirectory de la entrada ObjectAttributes.

Si la clave especificada por ObjectAttributes no existe, la rutina intenta crear la clave. Para que este intento se realice correctamente, la nueva clave debe ser una subclave directa de la clave a la que hace referencia RootDirectoryy la clave a la que hace referencia RootDirectory debe haberse abierto para KEY_CREATE_SUB_KEY acceso.

Si la clave especificada ya existe, se abre y su valor no se ve afectado de ninguna manera.

Los atributos de seguridad especificados por ObjectAttributes cuando se crea una clave determinan si el desiredAccess especificado se concede en llamadas posteriores a ZwCreateKey y ZwOpenKey.

Si el autor de la llamada no se está ejecutando en un contexto de subproceso del sistema, debe asegurarse de que los identificadores que cree sean identificadores privados. De lo contrario, el proceso puede acceder al identificador en cuyo contexto se está ejecutando el controlador. Para obtener más información, vea identificadores de objeto.

Para obtener más información sobre cómo trabajar con claves del Registro, vea Using the Registry in a Driver.

Si la llamada a esta función se produce en modo de usuario, debe usar el nombre "NtCreateKey" en lugar de "ZwCreateKey".

La rutina de NtCreateKey en el kernel de Windows no es accesible directamente para los controladores en modo kernel.

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)