TmCreateEnlistment - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
// wdm.h

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
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-wdm-tmcreateenlistment)

TmCreateEnlistment function

Description

The TmCreateEnlistment routine creates a new enlistment object for a transaction.

Parameters

EnlistmentHandle [out]

A pointer to a caller-allocated variable that receives a handle to the new enlistment object if the call to TmCreateEnlistment succeeds.

PreviousMode [in]

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.

DesiredAccess [in]

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.

ObjectAttributes [in]

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.

ResourceManager [in]

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.

Transaction [in]

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.

CreateOptions [in, optional]

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.

NotificationMask [in]

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.

EnlistmentKey [in, optional]

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 Tm*Xxx* routines instead of Zw*Xxx* routines, see Using TmXxx Routines.

See also

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObReferenceObjectByHandle

ResourceManagerNotification

ZwCreateEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenResourceManager

ZwOpenTransaction

View the official Windows Driver Kit DDI reference

Edit description on GitHub