Función ZwOpenKeyTransactedEx (wdm.h)

Artículo
08/08/2023

La rutina ZwOpenKeyTransactedEx abre una clave del Registro existente y asocia la clave a una transacción.

Sintaxis

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

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.

[in] OpenOptions

Especifica las opciones que se aplicarán al abrir 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 OpenOptions	Descripción
REG_OPTION_OPEN_LINK	La clave es un vínculo simbólico. El dispositivo y los controladores intermedios no usan esta marca.
REG_OPTION_BACKUP_RESTORE	La clave debe abrirse con privilegios especiales que permitan 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.

Valor devuelto

ZwOpenKeyTransactedEx devuelve STATUS_SUCCESS si la llamada 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.
STATUS_INVALID_PARAMETER_4	El valor del parámetro OpenOptions 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.

Si la clave especificada no existe en el Registro, ZwOpenKeyTransactedEx devuelve un valor de estado de error y no proporciona un identificador de clave. A diferencia de la rutina ZwCreateKeyTransacted , la rutina ZwOpenKeyTransactedEx no crea la clave especificada si la clave no existe. ZwCreateKeyTransacted y ZwOpenKeyTransactedEx asocian una clave del Registro con una transacción.

La rutina ZwOpenKeyEx es similar a ZwOpenKeyTransactedEx, pero no asocia una clave a una transacción.

La rutina ZwOpenKeyTransacted es similar a ZwOpenKeyTransactedEx , pero no acepta un parámetro OpenOptions . El parámetro OpenOptions de ZwOpenKeyTransactedEx permite al autor de la llamada abrir una clave que es un vínculo simbólico o abrir una clave para las operaciones de copia de seguridad y restauración. Una llamada a ZwOpenKeyTransactedEx con el parámetro OpenOptions establecido en cero equivale a una llamada a ZwOpenKeyTransacted.

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 ZwOpenKeyTransactedEx pueden asociar una o varias claves a la transacción.
La llamada especifica, como parámetro de entrada, un identificador de clave del Registro que obtuvo una llamada a ZwCreateKeyTransacted o ZwOpenKeyTransactedEx 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.

ZwOpenKeyTransactedEx omite la información de seguridad de la estructura a la que apunta el parámetro ObjectAttributes .

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 7 y versiones posteriores del sistema operativo 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)