TmCreateEnlistment function (wdm.h)
The TmCreateEnlistment routine creates a new enlistment object for a transaction.
Syntax
NTSTATUS TmCreateEnlistment(
[out] PHANDLE EnlistmentHandle,
[in] KPROCESSOR_MODE PreviousMode,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] PRKRESOURCEMANAGER ResourceManager,
[in] PKTRANSACTION Transaction,
[in, optional] ULONG CreateOptions,
[in] NOTIFICATION_MASK NotificationMask,
[in, optional] PVOID EnlistmentKey
);
Parameters
[out] EnlistmentHandle
A pointer to a caller-allocated variable that receives a handle to the new enlistment object if the call to TmCreateEnlistment succeeds.
[in] PreviousMode
The processor mode of the process that will use the enlistment handle to access the enlistment object. This value must be either UserMode or KernelMode.
[in] DesiredAccess
An ACCESS_MASK value that specifies the caller's requested access to the enlistment object. For more information about this parameter, see the description of the DesiredAccess parameter for ZwCreateEnlistment.
[in] 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] ResourceManager
A pointer to a resource manager object. To obtain this pointer, your component must call ObReferenceObjectByHandle and supply the object handle that a previous call to ZwCreateResourceManager or ZwOpenResourceManager provided.
[in] Transaction
A pointer to a transaction object. To obtain this pointer, your component must call ObReferenceObjectByHandle and supply the object handle that a previous call to ZwCreateTransaction or ZwOpenTransaction provided. KTM adds this transaction to the list of transactions that the calling resource manager is handling.
[in, optional] CreateOptions
Enlistment option flags. The following table contains the only available flag.
| CreateOptions flag | Meaning |
|---|---|
| ENLISTMENT_SUPERIOR | The caller is enlisting as a superior transaction manager for the specified transaction. |
This parameter is optional and can be zero.
[in] NotificationMask
A bitwise OR of the TRANSACTION_NOTIFY_XXX values that are defined in Ktmtypes.h. This mask value specifies the types of transaction notifications that KTM sends to the caller.
[in, optional] EnlistmentKey
A pointer to caller-defined information that uniquely identifies the enlistment. The resource manager receives this pointer when it calls ZwGetNotificationResourceManager or when KTM calls the ResourceManagerNotification callback routine. The resource manager can maintain a reference count for this key by calling TmReferenceEnlistmentKey and TmDereferenceEnlistmentKey. This parameter is optional and can be NULL.
Return value
TmCreateEnlistment returns STATUS_SUCCESS if the operation succeeds. Otherwise, this routine might return one of the following values:
| Return code | Description |
|---|---|
|
The value of the CreateOptions or NotificationMask parameter is invalid, or KTM could not find the transaction that the Transaction parameter specifies. |
|
A memory allocation failed. |
|
The enlistment failed because KTM or the resource manager is not in an operational state. |
|
The enlistment failed because the transaction that the Transaction parameter specifies is not active. |
|
The caller tried to register as a superior transaction manager but a superior enlistment already exists. |
|
The caller is trying to register as a superior transaction manager, but the caller's resource manager object is volatile while the associated transaction manager object is not volatile. |
|
The value of the DesiredAccess parameter is invalid. |
The routine might return other NTSTATUS values.
Remarks
The TmCreateEnlistment routine is a pointer-based version of the ZwCreateEnlistment routine.
For information about when to use KTM's TmXxx routines instead of ZwXxx routines, see Using TmXxx 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, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |