Edit

Share via

CreateEnlistment function (ktmw32.h)

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

See also

CommitComplete

CommitEnlistment

Kernel Transaction Manager Functions

NOTIFICATION_MASK

OpenEnlistment

TRANSACTION_NOTIFICATION