Función ZwCreateKey (wdm.h)

Artículo
08/08/2023

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 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 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 de 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 deben aplicar al crear o abrir una clave, especificada como una combinación compatible de las marcas siguientes.

Marca 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 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.

Valor de disposició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 si se ejecuta correctamente o el código de error NTSTATUS adecuado en caso de error.

Comentarios

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 Uso del Registro en un controlador.

Una vez que el identificador 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 miembro ObjectName de la entrada ObjectAttributes. Los nombres de ruta de acceso de las claves del Registro comienzan por \Registry.
Como pathname relativo 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 RootDirectory y 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 se concede el DesiredAccess especificado 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 ejecuta 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, consulte Uso del Registro en un controlador.

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

La rutina NtCreateKey del 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 versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar 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 NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)