NtOpenTransactionManager - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTTMAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenTransactionManager(
_Out_ PHANDLE TmHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_opt_ PCUNICODE_STRING LogFileName,
_In_opt_ LPGUID TmIdentity,
_In_opt_ ULONG OpenOptions
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenTransactionManager(
_Out_ PHANDLE TmHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_opt_ PCUNICODE_STRING LogFileName,
_In_opt_ LPGUID TmIdentity,
_In_opt_ ULONG OpenOptions
);
View code on GitHub// wdm.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenTransactionManager(
[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
);
View the official Windows Driver Kit DDI reference// wdm.h
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
);
View the official Windows Driver Kit DDI referenceThe ZwOpenTransactionManager routine obtains a handle to an existing transaction manager object.
TmHandle [out]A pointer to a caller-allocated variable that receives a handle to the transaction manager object if ZwOpenTransactionManager returns STATUS_SUCCESS.
DesiredAccess [in]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.
ObjectAttributes [in, optional]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.
LogFileName [in, optional]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.
TmIdentity [in, optional]A pointer to a GUID that identifies the transaction manager object. This parameter is optional and can be NULL.
OpenOptions [in, optional]This parameter is not used and must be zero.
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.
The caller can identify which transaction manager object to open by using one of the following three techniques:
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 Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
ZwQueryInformationTransactionManager
The ZwOpenTransactionManager routine obtains a handle to an existing transaction manager object.
TmHandle [out]A pointer to a caller-allocated variable that receives a handle to the transaction manager object if ZwOpenTransactionManager returns STATUS_SUCCESS.
DesiredAccess [in]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.
ObjectAttributes [in, optional]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.
LogFileName [in, optional]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.
TmIdentity [in, optional]A pointer to a GUID that identifies the transaction manager object. This parameter is optional and can be NULL.
OpenOptions [in, optional]This parameter is not used and must be zero.
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.
The caller can identify which transaction manager object to open by using one of the following three techniques:
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 Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
ZwQueryInformationTransactionManager