NtOpenTransaction - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTTMAPI_H
/**
* Opens an existing KTM transaction by its unit-of-work GUID. Use the identifier
* returned by TransactionBasicInformation; this does not create or reset it.
* Unlike NtOpenRegistryTransaction, lookup is not by an Object Manager name.
*
* \param TransactionHandle Required output receiving a separately owned handle
* on success. Close it with NtClose. Initialize before calling and check status.
* \param DesiredAccess Nonzero requested transaction rights. Query, set, commit,
* rollback and synchronous-wait requirements are independent rights.
* \param ObjectAttributes Optional handle attributes, not a transaction-name
* infoclass or a replacement security descriptor for an existing object.
* \param Uow Required readable GUID identifying the existing transaction; NULL
* returns STATUS_INVALID_PARAMETER. Native user-mode capture requires 4-byte
* GUID alignment.
* \param TmHandle Optional manager to scope lookup; NULL selects the global
* unbound-transaction namespace. Explicit-manager
* lookup has separate manager access/state checks.
* \return STATUS_SUCCESS or failure, including STATUS_TRANSACTION_NOT_FOUND for
* an unknown UOW. DesiredAccess = 0 returns STATUS_INVALID_PARAMETER.
* \remarks A second handle shares the transaction and outcome. A failed native
* lookup can preserve the caller's handle sentinel; the WoW64 wrapper
* copies back its NULL temporary after the native call. Do not use output without
* checking status. Registry-only transaction handles have no KTM UOW query here.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwopentransaction
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenTransaction(
_Out_ PHANDLE TransactionHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_ LPGUID Uow,
_In_opt_ HANDLE TmHandle
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenTransaction(
_Out_ PHANDLE TransactionHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_opt_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_ LPGUID Uow,
_In_opt_ HANDLE TmHandle
);
View code on GitHub// wdm.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenTransaction(
[out] PHANDLE TransactionHandle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in] LPGUID Uow,
[in, optional] HANDLE TmHandle
);
View the official Windows Driver Kit DDI reference// wdm.h
NTSYSCALLAPI NTSTATUS ZwOpenTransaction(
[out] PHANDLE TransactionHandle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in] LPGUID Uow,
[in, optional] HANDLE TmHandle
);
View the official Windows Driver Kit DDI referenceThe ZwOpenTransaction routine obtains a handle to an existing transaction object.
TransactionHandle [out]A pointer to a caller-allocated variable that receives a handle to the transaction object if ZwOpenTransaction returns STATUS_SUCCESS.
DesiredAccess [in]An ACCESS_MASK value that specifies the caller's requested access to the transaction object. For information about how to specify this parameter, see the DesiredAccess parameter of ZwCreateTransaction.
ObjectAttributes [in, optional]A pointer to an OBJECT_ATTRIBUTES structure that specifies the object's attributes. Use the InitializeObjectAttributes routine to initialize this structure, but specify only that routine's InitializedAttributes and Attributes parameters. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE flag in the Attributes parameter. The ObjectAttributes parameter is optional and can be NULL.
Uow [in]A pointer to a GUID that is a transaction object's unit of work (UOW) identifier. This GUID identifies the transaction object to open.
TmHandle [in, optional]A handle to a transaction manager object. If this parameter is not NULL, KTM searches only for transaction objects that belong to the specified transaction manager object. If this parameter is NULL, KTM searches all transaction objects.
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 DesiredAccess or Uow parameter was zero. |
| STATUS_OBJECT_TYPE_MISMATCH | The specified handle is not a handle to a transaction object. |
| STATUS_INVALID_HANDLE | An object handle is invalid. |
| STATUS_TRANSACTION_NOT_FOUND | KTM could not find the transaction object. |
| STATUS_ACCESS_DENIED | The value of the DesiredAccess parameter is invalid. |
The routine might return other NTSTATUS values.
Typically, a resource manager calls ZwOpenTransaction after it receives a transaction UOW from a transactional client that had previously called ZwCreateTransaction.
For more information about ZwOpenTransaction, see Creating a Resource Manager.
NtOpenTransaction and ZwOpenTransaction 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.
Using Nt and Zw Versions of the Native System Services Routines
The ZwOpenTransaction routine obtains a handle to an existing transaction object.
TransactionHandle [out]A pointer to a caller-allocated variable that receives a handle to the transaction object if ZwOpenTransaction returns STATUS_SUCCESS.
DesiredAccess [in]An ACCESS_MASK value that specifies the caller's requested access to the transaction object. For information about how to specify this parameter, see the DesiredAccess parameter of ZwCreateTransaction.
ObjectAttributes [in, optional]A pointer to an OBJECT_ATTRIBUTES structure that specifies the object's attributes. Use the InitializeObjectAttributes routine to initialize this structure, but specify only that routine's InitializedAttributes and Attributes parameters. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE flag in the Attributes parameter. The ObjectAttributes parameter is optional and can be NULL.
Uow [in]A pointer to a GUID that is a transaction object's unit of work (UOW) identifier. This GUID identifies the transaction object to open.
TmHandle [in, optional]A handle to a transaction manager object. If this parameter is not NULL, KTM searches only for transaction objects that belong to the specified transaction manager object. If this parameter is NULL, KTM searches all transaction objects.
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 DesiredAccess or Uow parameter was zero. |
| STATUS_OBJECT_TYPE_MISMATCH | The specified handle is not a handle to a transaction object. |
| STATUS_INVALID_HANDLE | An object handle is invalid. |
| STATUS_TRANSACTION_NOT_FOUND | KTM could not find the transaction object. |
| STATUS_ACCESS_DENIED | The value of the DesiredAccess parameter is invalid. |
The routine might return other NTSTATUS values.
Typically, a resource manager calls ZwOpenTransaction after it receives a transaction UOW from a transactional client that had previously called ZwCreateTransaction.
For more information about ZwOpenTransaction, see Creating a Resource Manager.
NtOpenTransaction and ZwOpenTransaction 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.
Using Nt and Zw Versions of the Native System Services Routines