Función ZwCreateKeyTransacted (wdm.h)

Artículo
03/08/2024

La rutina ZwCreateKeyTransacted crea una nueva clave del Registro o abre una existente y asocia la clave a una transacción.

Sintaxis

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

Parámetros

[out] KeyHandle

Puntero a una variable HANDLE en la que la rutina escribe el identificador en la clave.

[in] DesiredAccess

Especifica el tipo de acceso a la clave que solicita el autor de la llamada. Este parámetro es un valor de ACCESS_MASK . Para obtener más información, vea la descripción del parámetro DesiredAccess de la rutina ZwCreateKey .

[in] ObjectAttributes

Puntero a los atributos de objeto de la clave que se está abriendo. Este parámetro apunta a una estructura OBJECT_ATTRIBUTES que debe haber sido inicializada previamente por la rutina InitializeObjectAttributes . El llamador debe especificar el nombre de la clave del Registro como parámetro ObjectName en la llamada a InitializeObjectAttributes. 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

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

[in] CreateOptions

Especifica las opciones que se aplicarán cuando la rutina crea o abre la clave. Establezca este parámetro en cero o en el or bit a bit de uno o varios de los siguientes bits de marca REG_OPTION_XXX .

Marca CreateOptions	Descripción
REG_OPTION_VOLATILE	La clave no se conserva después de reiniciar el equipo.
REG_OPTION_NON_VOLATILE	La clave se conserva después de reiniciar el equipo.
REG_OPTION_CREATE_LINK	La clave es un vínculo simbólico. El dispositivo y los controladores intermedios no usan esta marca.
REG_OPTION_BACKUP_RESTORE	Abra la clave con privilegios especiales que habiliten las operaciones de copia de seguridad y restauración. El dispositivo y los controladores intermedios no usan esta marca.

[in] TransactionHandle

Identificador de un objeto de transacción. Para obtener este identificador, puede llamar a la rutina ZwCreateTransaction . O bien, si tiene un puntero a un objeto de transacción, puede proporcionar el puntero a la rutina ObOpenObjectByPointer para obtener el identificador de transacción correspondiente.

[out, optional] Disposition

Puntero a una ubicación en la que la rutina escribe uno de los siguientes valores para indicar si la llamada creó una nueva clave o abrió 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.

Puede establecer Disposition = NULL si esta información no es necesaria.

Valor devuelto

ZwCreateKeyTransacted devuelve STATUS_SUCCESS si la llamada crea o abre correctamente la clave. Entre los posibles valores devueltos de error se incluyen los siguientes:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El parámetro ObjectAttributes es NULL o apunta a información no válida, o bien el valor del parámetro CreateOptions especifica opciones no válidas.
STATUS_OBJECT_PATH_SYNTAX_BAD	La ruta de acceso del Registro en los atributos de objeto no es válida.
STATUS_OBJECT_NAME_NOT_FOUND	No se encontró la ruta de acceso del Registro en los atributos de objeto.
STATUS_ACCESS_DENIED	El autor de la llamada no tenía los derechos de acceso necesarios para abrir un identificador para la clave del Registro con nombre.
STATUS_INSUFFICIENT_RESOURCES	Error en una operación de asignación de memoria.

Comentarios

Esta rutina proporciona un identificador con el que el autor de la llamada puede acceder a una clave del Registro. Además, esta rutina asocia la clave a una transacción activa.

Una vez que el controlador al que apunta KeyHandle ya no se usa, el controlador debe llamar a la rutina ZwClose para cerrarlo.

Al igual que ZwCreateKeyTransacted, la rutina ZwOpenKeyTransacted asocia una clave a una transacción. A diferencia de ZwCreateKeyTransacted, que puede crear una nueva clave o abrir una clave existente, ZwOpenKeyTransacted solo puede abrir una clave del Registro que ya existe.

Después de que un controlador en modo kernel obtenga un identificador para una transacción (por ejemplo, llamando a ZwCreateTransaction), el controlador puede realizar una serie de operaciones del Registro que forman parte de esta transacción. El controlador puede cerrar la transacción confirmando los cambios realizados en la transacción o reviertiendo la transacción.

Una vez que el controlador complete correctamente todas las operaciones del Registro que forman parte de una transacción, puede llamar a la rutina ZwCommitTransaction para confirmar los cambios. El controlador puede llamar a la rutina ZwRollbackTransaction para revertir la transacción.

Durante una transacción, una operación del Registro forma parte de la transacción si la llamada del sistema que realiza la operación cumple cualquiera de las condiciones siguientes:

La llamada especifica, como parámetro de entrada, el identificador de transacción. Por ejemplo, las llamadas a ZwCreateKeyTransacted y ZwOpenKeyTransacted pueden asociar uno o varios identificadores a las claves del Registro con la transacción.
La llamada especifica, como parámetro de entrada, un identificador de clave del Registro que se obtuvo mediante una llamada a ZwCreateKeyTransacted o ZwOpenKeyTransacted al que se proporcionó el identificador de transacción. Por ejemplo, una llamada a la rutina ZwSetValueKey puede usar un identificador de clave que se obtuvo de esta manera para establecer el valor de una clave del Registro como parte de una transacción.

Para obtener más información sobre las transacciones en modo kernel, vea Uso del Administrador de transacciones de kernel.

El descriptor de seguridad de los atributos de objeto determina si los derechos de acceso especificados por el parámetro DesiredAccess se conceden en llamadas posteriores a rutinas, como ZwOpenKeyTransacted que acceden a la clave o a rutinas, como ZwCreateKeyTransacted, que crean subclaves de la clave.

Si el llamador en modo kernel no se está ejecutando en un contexto de subproceso del sistema, debe asegurarse de que los identificadores que cree sean identificadores de kernel. 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 en modo kernel, consulte Uso del Registro en un controlador.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de Windows.
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	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)