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 |
|---|---|
|
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 |