ZwOpenTransactionManager function (wdm.h)

Article
04/18/2022

The ZwOpenTransactionManager routine obtains a handle to an existing transaction manager object.

Syntax

NTSYSCALLAPI NTSTATUS ZwOpenTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] LPGUID             TmIdentity,
  [in, optional] ULONG              OpenOptions
);

Parameters

[out] TmHandle

A pointer to a caller-allocated variable that receives a handle to the transaction manager object if ZwOpenTransactionManager returns STATUS_SUCCESS.

[in] DesiredAccess

An ACCESS_MASK value that specifies the caller's requested access to the transaction manager object. For information about how to specify this parameter, see the DesiredAccess parameter of ZwCreateTransactionManager.

[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 the log file stream that was created when the transaction manager object was created. For more information, see the LogFileName parameter of ZwCreateTransactionManager. This parameter is optional and can be NULL.

[in, optional] TmIdentity

A pointer to a GUID that identifies the transaction manager object. This parameter is optional and can be NULL.

[in, optional] OpenOptions

This parameter is not used and must be zero.

Return value

ZwOpenTransactionManager 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_OBJECT_NAME_INVALID	The object name that the ObjectAttributes parameter specifies is invalid.
STATUS_LOG_CORRUPTION_DETECTED	KTM encountered an error while creating or opening the log file.
STATUS_ACCESS_DENIED	The value of the DesiredAccess parameter is invalid.

The routine might return other NTSTATUS values.

Remarks

The caller can identify which transaction manager object to open by using one of the following three techniques:

Use the LogFileName parameter to specify the path and file name of a log file stream that was created when the transaction manager object was created.
Use the TmIdentity parameter to specify the GUID that identifies the transaction manager object.
Use the ObjectAttributes parameter to supply an OBJECT_ATTRIBUTES structure that contains the object name that the caller previously specified to the ZwCreateTransactionManager routine.

You must specify only one of the above-listed parameters (an object name, a log file name, or a GUID) and set the other two parameters to NULL.

Your TPS component must call ZwRecoverTransactionManager after it has called ZwOpenTransactionManager.

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

For more information about how to use ZwOpenTransactionManager, see Transaction Manager Objects and Creating a Resource Manager.

NtOpenTransactionManager and ZwOpenTransactionManager 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)