CreateEnlistment function (ktmw32.h)

Article
10/13/2021

Creates an enlistment, sets its initial state, and opens a handle to the enlistment with the specified access.

Syntax

HANDLE CreateEnlistment(
  [in, optional] LPSECURITY_ATTRIBUTES lpEnlistmentAttributes,
  [in]           HANDLE                ResourceManagerHandle,
  [in]           HANDLE                TransactionHandle,
  [in]           NOTIFICATION_MASK     NotificationMask,
  [in, optional] DWORD                 CreateOptions,
  [in, optional] PVOID                 EnlistmentKey
);

Parameters

[in, optional] lpEnlistmentAttributes

A pointer to a SECURITY_ATTRIBUTES structure that contains the security attributes for the enlistment manager. Specify NULL to obtain the default attributes.

[in] ResourceManagerHandle

A handle to the resource manager (RM) to enlist.

[in] TransactionHandle

A handle to the transaction in which the RM is enlisting.

[in] NotificationMask

The notifications this RM is requesting for the TransactionHandle parameter. For a list of valid values, see NOTIFICATION_MASK.

[in, optional] CreateOptions

Any optional enlistment instructions.

Value	Meaning
ENLISTMENT_SUPERIOR 1	Enlist as a superior transaction manager.

[in, optional] EnlistmentKey

A pointer to a user-defined structure used by the RM that is returned when a notification is sent in the TRANSACTION_NOTIFICATION structure. This is typically used to associate a private structure with this specific transaction.

Return value

If the function succeeds, the return value is a handle to the enlistment.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call the GetLastError function.

The following list identifies the possible error codes:

Remarks

Windows Vista: Any attempt to enlist during the pre-prepare phase or later will fail.

If you do not specify within your notification mask that you accept a single-phase commit request, KTM always performs a two-phase commit operation.

Keep the following notification rules in mind when enlisting in transactions:

The RM must always request rollback notification.
If the RM requests prepare notification, it must also request commit notification.
If the RM requests a single-phase commit operation, it must also specify prepare and commit notifications.
The only time an RM is not required to request commit notifications is when it is requesting at least a pair of prepare and rollback notifications.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	ktmw32.h
Library	KtmW32.lib
DLL	KtmW32.dll