Función NtCreateTransaction (wdm.h)

Artículo
03/14/2023

La rutina ZwCreateTransaction crea un objeto de transacción.

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Parámetros

[out] TransactionHandle

Puntero a una variable asignada por el autor de la llamada que recibe un identificador para el nuevo objeto de transacción, si la llamada a ZwCreateTransaction se realiza correctamente.

[in] DesiredAccess

Valor de ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto de transacción. Además de los derechos de acceso definidos para todo tipo de objetos (vea ACCESS_MASK), el autor de la llamada puede especificar cualquiera de las marcas siguientes para los objetos de transacción.

Máscara de acceso	Permite al autor de la llamada
TRANSACTION_COMMIT	Confirme la transacción (consulte ZwCommitTransaction).
TRANSACTION_ENLIST	Cree una inscripción para la transacción (consulte ZwCreateEnlistment).
TRANSACTION_PROPAGATE	No debe usarse.
TRANSACTION_QUERY_INFORMATION	Obtenga información sobre la transacción (consulte ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Revierte la transacción (consulte ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Establezca información para la transacción (consulte ZwSetInformationTransaction).

Como alternativa, puede especificar uno o varios de los siguientes ACCESS_MASK mapas de bits. Estos mapas de bits combinan las marcas de la tabla anterior con las marcas STANDARD_RIGHTS_XXX que se describen en la página de referencia de ACCESS_MASK . También puede combinar estos mapas de bits con marcas adicionales de la tabla anterior. En la tabla siguiente se muestra cómo se corresponden los mapas de bits con derechos de acceso específicos.

Mapa de bits de derechos	Conjunto de derechos de acceso específicos
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION y SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT y SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK y SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE y TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE y SYNCHRONIZE

Normalmente, un administrador de recursos especifica TRANSACTION_RESOURCE_MANAGER_RIGHTS.

El valor DesiredAccess no puede ser cero.

[in, optional] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use la rutina 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. Este parámetro es opcional y puede ser NULL.

[in, optional] Uow

Puntero a un GUID que KTM usa como identificador de unidad de trabajo (UOW) del nuevo objeto de transacción. Este parámetro es opcional y puede ser NULL. Si este parámetro es NULL, KTM genera un GUID y lo asigna al objeto de transacción. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] TmHandle

Identificador de un objeto de administrador de transacciones obtenido por una llamada anterior a ZwCreateTransactionManager o ZwOpenTransactionManager. KTM asigna el nuevo objeto de transacción al objeto de administrador de transacciones especificado. Si este parámetro es NULL, KTM asigna el nuevo objeto de transacción a un administrador de transacciones más adelante, cuando un administrador de recursos crea una inscripción para la transacción.

[in, optional] CreateOptions

Marcas de creación de objetos opcionales. La tabla siguiente contiene las marcas disponibles, que se definen en Ktmtypes.h.

Marca de opción	Significado
TRANSACTION_DO_NOT_PROMOTE	Reservado para un uso futuro.

[in, optional] IsolationLevel

Reservado para un uso futuro. Los autores de llamadas deben establecer este parámetro en cero.

[in, optional] IsolationFlags

Reservado para uso futuro. Los autores de llamadas deben establecer este parámetro en cero.

[in, optional] Timeout

Puntero a un valor de tiempo de espera. Si el tiempo especificado por este parámetro no ha confirmado la transacción, KTM revierte la transacción. El valor de tiempo de espera se expresa en unidades de tiempo del sistema (intervalos de 100 nanosegundos) y puede especificar una hora absoluta o una hora relativa. Si el valor al que apunta Timeout es negativo, la hora de expiración es relativa a la hora actual del sistema. De lo contrario, la hora de expiración es absoluta. Este puntero es opcional y puede ser NULL si no desea que la transacción tenga un valor de tiempo de espera. Si Timeout = NULL o *Timeout = 0, la transacción nunca agota el tiempo de espera. (También puede usar ZwSetInformationTransaction para establecer un valor de tiempo de espera).

[in, optional] Description

Puntero a una estructura de UNICODE_STRING proporcionada por el autor de la llamada que contiene una cadena terminada en NULL. La cadena proporciona una descripción de la transacción. KTM almacena una copia de la cadena e incluye la cadena en los mensajes que escribe en la secuencia de registro. La longitud máxima de la cadena es MAX_TRANSACTION_DESCRIPTION_LENGTH. Este parámetro es opcional y puede ser NULL.

Valor devuelto

ZwCreateTransaction devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, esta rutina podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El parámetro CreateOptions contiene una marca no válida, el parámetro DesiredAccess es cero o la cadena del parámetro Description es demasiado larga.
STATUS_INSUFFICIENT_RESOURCES	KTM no pudo asignar recursos del sistema (normalmente memoria).
STATUS_INVALID_ACL	Un descriptor de seguridad contiene una lista de control de acceso (ACL) no válida.
STATUS_INVALID_SID	Un descriptor de seguridad contiene un identificador de seguridad (SID) no válido.
STATUS_OBJECT_NAME_EXISTS	El nombre de objeto que el parámetro ObjectAttributes especifica ya existe.
STATUS_OBJECT_NAME_INVALID	El nombre de objeto que especifica el parámetro ObjectAttributes no es válido.
STATUS_ACCESS_DENIED	El valor del parámetro DesiredAccess no es válido.

La rutina podría devolver otros valores NTSTATUS.

Comentarios

El llamador puede usar el parámetro Uow para especificar un identificador UOW para el objeto de transacción. Si el autor de la llamada no especifica un identificador UOW, KTM genera un GUID y lo asigna al objeto de transacción. El llamador puede obtener más adelante este GUID mediante una llamada a ZwQueryInformationTransaction.

Normalmente, debe permitir que KTM genere un GUID para el objeto de transacción, a menos que el componente se comunique con otro componente TPS que ya haya generado un identificador UOW para la transacción.

Para cerrar el identificador de transacción, el componente que llamó a ZwCreateTransaction debe llamar a ZwClose. Si el último identificador de transacción se cierra antes de que cualquier componente llame a ZwCommitTransaction para la transacción, KTM revierte la transacción.

Para obtener más información sobre cómo los clientes de transacciones deben usar ZwCreateTransaction, vea Creating a Transactional Client.

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services 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 NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores del sistema operativo.
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, PowerIrpDDis