Compartir a través de


Función ZwCreateKeyTransacted (wdm.h)

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)

Consulte también

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObOpenObjectByPointer

ZwClose

ZwCommitTransaction

ZwCreateKey

ZwCreateTransaction

ZwOpenKeyTransacted

ZwRollbackTransaction

ZwSetValueKey