Export (0) Print
Expand All

CreateEnlistment function

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

Syntax


HANDLE WINAPI CreateEnlistment(
  _In_opt_  LPSECURITY_ATTRIBUTES lpEnlistmentrAttributes,
  _In_      HANDLE ResourceManagerHandle,
  _In_      HANDLE TransactionHandle,
  _In_      NOTIFICATION_MASK NotificationMask,
  _In_opt_  DWORD CreateOptions,
  _In_opt_  PVOID EnlistmentKey
);

Parameters

lpEnlistmentrAttributes [in, optional]

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

ResourceManagerHandle [in]

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

TransactionHandle [in]

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

NotificationMask [in]

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

CreateOptions [in, optional]

Any optional enlistment instructions.

ValueMeaning
ENLISTMENT_SUPERIOR
1

Enlist as a superior transaction manager.

 

EnlistmentKey [in, optional]

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:

ERROR_INSUFFICIENT_RESOURCES
ERROR_INVALID_PARAMETER
ERROR_INVALID_ACL
ERROR_INVALID_SID
ERROR_NO_SYSTEM_RESOURCES
ERROR_OBJECT_NAME_COLLISION
ERROR_OBJECT_NAME_EXISTS
ERROR_OBJECT_NAME_INVALID
ERROR_OBJECT_TYPE_MISMATCH
ERROR_PRIVILEGE_NOT_HELD
ERROR_UNKNOWN_REVISION

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 preprepare and rollback notifications.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008

Header

KtmW32.h

Library

KtmW32.lib

DLL

KtmW32.dll

See also

CommitComplete
CommitEnlistment
Kernel Transaction Manager Functions
NOTIFICATION_MASK
OpenEnlistment
TRANSACTION_NOTIFICATION

 

 

Community Additions

ADD
Show:
© 2014 Microsoft