ZwCreateTransactionManager function (wdm.h)

  • Article

The ZwCreateTransactionManager routine creates a new transaction manager object.

Syntax

NTSYSCALLAPI NTSTATUS ZwCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Parameters

[out] TmHandle

A pointer to a caller-allocated variable that receives a handle to the new transaction manager object.

[in] DesiredAccess

An ACCESS_MASK value that specifies the caller's requested access to the transaction manager 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 access right flags for transaction manager objects.

ACCESS_MASK flag Allows the caller to
TRANSACTIONMANAGER_CREATE_RM Create a resource manager (see ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION Obtain information about the transaction manager (see ZwQueryInformationTransactionManager and ZwEnumerateTransactionObject). Also required for ZwOpenResourceManager, ZwCreateTransaction, and ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER Recover the transaction manager (see ZwRecoverTransactionManager and ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME Not used.
TRANSACTIONMANAGER_SET_INFORMATION Not used.
 

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
TRANSACTIONMANAGER_GENERIC_READ STANDARD_RIGHTS_READ and TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME, and TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE, and TRANSACTIONMANAGER_GENERIC_EXECUTE

[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] LogFileName

A pointer to a UNICODE_STRING structure that contains the path and file name of a CLFS log file stream to be associated with the transaction manager object. This parameter must be NULL if the CreateOptions parameter is TRANSACTION_MANAGER_VOLATILE. Otherwise, this parameter must be non-NULL. For more information, see the following Remarks section.

[in, optional] CreateOptions

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

Option flag Meaning
TRANSACTION_MANAGER_VOLATILE The transaction manager object will be volatile. Therefore, it will not use a log file.
TRANSACTION_MANAGER_COMMIT_DEFAULT For internal use only.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME For internal use only.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES For internal use only.
TRANSACTION_MANAGER_COMMIT_LOWEST For internal use only.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY For internal use only.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS For internal use only.

[in, optional] CommitStrength

Reserved for future use. This parameter must be zero.

Return value

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

Return code Description
STATUS_INVALID_PARAMETER
 The value of an input parameter is invalid.
STATUS_INSUFFICIENT_RESOURCES
 KTM could not allocate system resources (typically memory).
STATUS_LOG_CORRUPTION_DETECTED
 KTM encountered an error while creating or opening the log file.
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_COLLISION
 The operating system detected a duplicate object name. The error might indicate that the log stream is already being used.
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

If the log file stream that the LogFileName parameter specifies does not exist, KTM calls CLFS to create the stream. If the stream already exists, KTM calls CLFS to open the stream.

Your TPS component must call ZwRecoverTransactionManager after it has called ZwCreateTransactionManager

If your TPS component specifies the TRANSACTION_MANAGER_VOLATILE flag in the CreateOptions parameter, all resource managers that are associated with the transaction manager object must specify the RESOURCE_MANAGER_VOLATILE flag when they call ZwCreateResourceManager.

A TPS component that calls ZwCreateTransactionManager must eventually call ZwClose to close the object handle.

For more information about how use ZwCreateTransactionManager, see Creating a Resource Manager.

NtCreateTransactionManager and ZwCreateTransactionManager are two versions of the same Windows Native System Services routine.

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, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI compliance rules HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

See also

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

Using Nt and Zw Versions of the Native System Services Routines

ZwClose

ZwOpenTransactionManager

ZwQueryInformationTransactionManager

ZwRecoverTransactionManager

ZwRollforwardTransactionManager