TmCreateEnlistment function (wdm.h)

Article
02/25/2022

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
STATUS_INVALID_PARAMETER	The value of the CreateOptions or NotificationMask parameter is invalid, or KTM could not find the transaction that the Transaction parameter specifies.
STATUS_INSUFFICIENT_RESOURCES	A memory allocation failed.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	The enlistment failed because KTM or the resource manager is not in an operational state.
STATUS_TRANSACTION_NOT_ACTIVE	The enlistment failed because the transaction that the Transaction parameter specifies is not active.
STATUS_TRANSACTION_SUPERIOR_EXISTS	The caller tried to register as a superior transaction manager but a superior enlistment already exists.
STATUS_TM_VOLATILE	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.
STATUS_ACCESS_DENIED	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