Функция TmCreateEnlistment (wdm.h)

Статья
08/08/2023

Подпрограмма TmCreateEnlistment создает новый объект зачисления для транзакции.

Синтаксис

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

Параметры

[out] EnlistmentHandle

Указатель на переменную, выделенную вызывающим объектом, которая получает дескриптор нового объекта зачисления, если вызов TmCreateEnlistment завершается успешно.

[in] PreviousMode

Режим процессора процесса, который будет использовать дескриптор зачисления для доступа к объекту зачисления. Это значение должно иметь значение UserMode или KernelMode.

[in] DesiredAccess

Значение ACCESS_MASK , указывающее запрошенный доступ вызывающего объекта к объекту зачисления. Дополнительные сведения об этом параметре см. в описании параметра DesiredAccess для ZwCreateEnlistment.

[in] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , указывающую имя объекта и другие атрибуты. Используйте подпрограмму InitializeObjectAttributes для инициализации этой структуры. Если вызывающий объект не выполняется в контексте системного потока, он должен задать атрибут OBJ_KERNEL_HANDLE при вызове InitializeObjectAttributes. Этот параметр является необязательным и может иметь значение NULL.

[in] ResourceManager

Указатель на объект Resource Manager. Чтобы получить этот указатель, компонент должен вызвать ObReferenceObjectByHandle и предоставить дескриптор объекта, указанный в предыдущем вызове ZwCreateResourceManager или ZwOpenResourceManager .

[in] Transaction

Указатель на объект транзакции. Чтобы получить этот указатель, компонент должен вызвать ObReferenceObjectByHandle и предоставить дескриптор объекта, указанный в предыдущем вызове ZwCreateTransaction или ZwOpenTransaction . KTM добавляет эту транзакцию в список транзакций, обрабатываемых вызывающим диспетчером ресурсов.

[in, optional] CreateOptions

Флаги параметров зачисления. В следующей таблице содержится единственный доступный флаг.

Флаг CreateOptions	Значение
ENLISTMENT_SUPERIOR	Вызывающий объект завербовается в качестве превосходного диспетчера транзакций для указанной транзакции.

Этот параметр является необязательным и может быть равен нулю.

[in] NotificationMask

Побитовое ИЛИ значений TRANSACTION_NOTIFY_XXX, определенных в Ktmtypes.h. Это значение маски указывает типы уведомлений о транзакциях , которые KTM отправляет вызывающей объекту.

[in, optional] EnlistmentKey

Указатель на определяемые вызывающим абонентом сведения, которые однозначно идентифицируют зачисление. Диспетчер ресурсов получает этот указатель при вызове ZwGetNotificationResourceManager или при вызове KTM процедуры обратного вызова ResourceManagerNotification . Диспетчер ресурсов может поддерживать количество ссылок для этого ключа, вызывая TmReferenceEnlistmentKey и TmDereferenceEnlistmentKey. Этот параметр является необязательным и может иметь значение NULL.

Возвращаемое значение

TmCreateEnlistment возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае эта подпрограмма может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Недопустимое значение параметра CreateOptions или NotificationMask , либо KTM не удалось найти транзакцию, указанную параметром Transaction .
STATUS_INSUFFICIENT_RESOURCES	Сбой выделения памяти.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	Не удалось выполнить зачисление, так как KTM или диспетчер ресурсов не находится в рабочем состоянии.
STATUS_TRANSACTION_NOT_ACTIVE	Не удалось выполнить зачисление, так как транзакция, указанная параметром Transaction , неактивна.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Вызывающий попытался зарегистрироваться в качестве вышестоящего диспетчера транзакций , но его уже существует.
STATUS_TM_VOLATILE	Вызывающий объект пытается зарегистрировать в качестве вышестоящего диспетчера транзакций, но объект диспетчера ресурсов вызывающего объекта не является переменным , а связанный объект диспетчера транзакций не является переменным.
STATUS_ACCESS_DENIED	Недопустимое значение параметра DesiredAccess .

Подпрограмма может возвращать другие значения NTSTATUS.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows Vista и более поздних версиях операционной системы.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL