NtCreateTransaction function (wdm.h)

Article
03/13/2023

The ZwCreateTransaction routine creates a transaction object.

Syntax

__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
);

Parameters

[out] TransactionHandle

A pointer to a caller-allocated variable that receives a handle to the new transaction object, if the call to ZwCreateTransaction succeeds.

[in] DesiredAccess

An ACCESS_MASK value that specifies the caller's requested access to the transaction object. In addition to the access rights that are defined for all kinds of objects (see ACCESS_MASK), the caller can specify any of the following flags for transaction objects.

Access mask	Allows the caller to
TRANSACTION_COMMIT	Commit the transaction (see ZwCommitTransaction).
TRANSACTION_ENLIST	Create an enlistment for the transaction (see ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Do not use.
TRANSACTION_QUERY_INFORMATION	Obtain information about the transaction (see ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Roll back the transaction (see ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Set information for the transaction (see ZwSetInformationTransaction).

Alternatively, you can specify one or more of the following ACCESS_MASK bitmaps. These bitmaps combine the flags from the previous table with the STANDARD_RIGHTS_XXX flags that are described on the ACCESS_MASK reference page. You can also combine these bitmaps with additional flags from the preceding table. The following table shows how the bitmaps correspond to specific access rights.

Rights bitmap	Set of specific access rights
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION, and SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT, and SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK, and SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE, and TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, and SYNCHRONIZE

Typically, a resource manager specifies TRANSACTION_RESOURCE_MANAGER_RIGHTS.

The DesiredAccess value cannot be zero.

[in, optional] ObjectAttributes

A pointer to an OBJECT_ATTRIBUTES structure that specifies the object name and other attributes. Use the InitializeObjectAttributes routine to initialize this structure. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes. This parameter is optional and can be NULL.

[in, optional] Uow

A pointer to a GUID that KTM uses as the new transaction object's unit of work (UOW) identifier. This parameter is optional and can be NULL. If this parameter is NULL, KTM generates a GUID and assigns it to the transaction object. For more information, see the following Remarks section.

[in, optional] TmHandle

A handle to a transaction manager object that was obtained by a previous call to ZwCreateTransactionManager or ZwOpenTransactionManager. KTM assigns the new transaction object to the specified transaction manager object. If this parameter is NULL, KTM assigns the new transaction object to a transaction manager later, when a resource manager creates an enlistment for the transaction.

[in, optional] CreateOptions

Optional object creation flags. The following table contains the available flags, which are defined in Ktmtypes.h.

Option flag	Meaning
TRANSACTION_DO_NOT_PROMOTE	Reserved for future use.

[in, optional] IsolationLevel

Reserved for future use. Callers must set this parameter to zero.

[in, optional] IsolationFlags

Reserved for future use. Callers should set this parameter to zero.

[in, optional] Timeout

A pointer to a time-out value. If the transaction has not been committed by the time specified by this parameter, KTM rolls back the transaction. The time-out value is expressed in system time units (100-nanosecond intervals), and can specify either an absolute time or a relative time. If the value pointed to by Timeout is negative, the expiration time is relative to the current system time. Otherwise, the expiration time is absolute. This pointer is optional and can be NULL if you do not want the transaction to have a time-out value. If Timeout = NULL or *Timeout = 0, the transaction never times out. (You can also use ZwSetInformationTransaction to set a time-out value.)

[in, optional] Description

A pointer to a caller-supplied UNICODE_STRING structure that contains a NULL-terminated string. The string provides a description of the transaction. KTM stores a copy of the string and includes the string in messages that it writes to the log stream. The maximum string length is MAX_TRANSACTION_DESCRIPTION_LENGTH. This parameter is optional and can be NULL.

Return value

ZwCreateTransaction returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	The CreateOptions parameter contains an invalid flag, the DesiredAccess parameter is zero, or the Description parameter's string is too long.
STATUS_INSUFFICIENT_RESOURCES	KTM could not allocate system resources (typically memory).
STATUS_INVALID_ACL	A security descriptor contains an invalid access control list (ACL).
STATUS_INVALID_SID	A security descriptor contains an invalid security identifier (SID).
STATUS_OBJECT_NAME_EXISTS	The object name that the ObjectAttributes parameter specifies already exists.
STATUS_OBJECT_NAME_INVALID	The object name that the ObjectAttributes parameter specifies is invalid.
STATUS_ACCESS_DENIED	The value of the DesiredAccess parameter is invalid.

The routine might return other NTSTATUS values.

Remarks

The caller can use the Uow parameter to specify a UOW identifier for the transaction object. If the caller does not specify a UOW identifier, KTM generates a GUID and assigns it to the transaction object. The caller can later obtain this GUID by calling ZwQueryInformationTransaction.

Typically, you should let KTM generate a GUID for the transaction object, unless your component communicates with another TPS component that has already generated a UOW identifier for the transaction.

To close the transaction handle, the component that called ZwCreateTransaction must call ZwClose. If the last transaction handle closes before any component calls ZwCommitTransaction for the transaction, KTM rolls back the transaction.

For more information about how transaction clients should use ZwCreateTransaction, see Creating a Transactional Client.

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later operating system versions.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs, PowerIrpDDis