ZwCreateTransactionManager function (wdm.h)
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 |
|---|---|
|
The value of an input parameter is invalid. |
|
KTM could not allocate system resources (typically memory). |
|
KTM encountered an error while creating or opening the log file. |
|
A security descriptor contains an invalid access control list (ACL). |
|
A security descriptor contains an invalid security identifier (SID). |
|
The object name that the ObjectAttributes parameter specifies already exists. |
|
The operating system detected a duplicate object name. The error might indicate that the log stream is already being used. |
|
The object name that the ObjectAttributes parameter specifies is invalid. |
|
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
Using Nt and Zw Versions of the Native System Services Routines