Поделиться через


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

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

Параметры

[out] EnlistmentHandle

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

[in] DesiredAccess

Значение ACCESS_MASK , указывающее запрошенный доступ вызывающего объекта к объекту зачисления. Помимо прав доступа, определенных для всех типов объектов (см . ACCESS_MASK), вызывающий объект может указать любой из следующих флагов прав доступа для объектов зачисления:

флаг ACCESS_MASK Разрешает вызывающей
ENLISTMENT_QUERY_INFORMATION Запрос сведений о зачислении (см. ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION Задайте сведения для зачисления (см . ZwSetInformationEnlistment).
ENLISTMENT_RECOVER Восстановите зачисление (см . ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS Выполнение операций, выполняемых диспетчером ресурсов, который не является превосходным (см. ZwRollbackEnlistment, ZwPrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS Выполнение операций, которые должен выполнять вышестоящий диспетчер транзакций (см. ZwPrepareEnlistment, ZwPreprepareEnlistment, ZwCommitEnlistment).
 

Кроме того, можно указать одно или несколько следующих ACCESS_MASK растровых рисунков. Эти точечные изображения объединяют флаги из предыдущей таблицы с флагами STANDARD_RIGHTS_XXX, описанными на странице справки по ACCESS_MASK . Вы также можете объединить эти растровые изображения с дополнительными флагами из предыдущей таблицы. В следующей таблице показано, как растровые изображения соответствуют определенным правам доступа.

Универсальное право доступа Набор определенных прав доступа
ENLISTMENT_GENERIC_READ STANDARD_RIGHTS_READ и ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS и ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS и ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE и ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Дескриптор объекта диспетчера ресурсов вызывающего объекта, который был получен при предыдущем вызове ZwCreateResourceManager или ZwOpenResourceManager.

[in] TransactionHandle

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

[in, optional] ObjectAttributes

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

[in, optional] CreateOptions

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

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

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

[in] NotificationMask

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

[in, optional] EnlistmentKey

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

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

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

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

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

Комментарии

Диспетчер ресурсов вызывает ZwCreateEnlistment для зачисления в транзакцию.

Диспетчеры ресурсов, которые не являются вышестоящими, должны включать флаг ENLISTMENT_SUBORDINATE_RIGHTS в маску доступа.

Диспетчеры транзакций высшего звена должны включать флаг ENLISTMENT_SUPERIOR_RIGHTS в свои маски доступа. Как правило, превосходный диспетчер транзакций включает код, который вызывает ZwRollbackEnlistment, поэтому он должен также включать флаг ENLISTMENT_SUBORDINATE_RIGHTS.

Диспетчер ресурсов, вызывающий ZwCreateEnlistment , должен в конечном итоге вызвать ZwClose , чтобы закрыть дескриптор объекта.

Диспетчер ресурсов может использовать параметр EnlistmentKey для назначения уникального значения каждому зачислению, например указателя на структуру данных, содержащую сведения о зачислении. Например, если диспетчер ресурсов сохраняет дескриптор объекта зачисления в структуре , диспетчер ресурсов может выполнить следующие действия:

  1. Вызовите ZwGetNotificationResourceManager , чтобы получить уведомление.
  2. Получите значение ключа зачисления из структуры TRANSACTION_NOTIFICATION .
  3. Используйте ключ зачисления, чтобы найти хранимый дескриптор объекта зачисления.
  4. Вызывайте подпрограммы, требующие дескриптора зачисления в качестве входных данных, например ZwCommitComplete или ZwRollbackComplete.
Дополнительные сведения о ZwCreateEnlistment см. в разделах Создание Resource Manager и Создание превосходного диспетчера транзакций.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx и ZwXxx см. в разделе Использование версий Nt и Zw для процедур собственных системных служб.

Требования

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

См. также раздел

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

TRANSACTION_NOTIFICATION

Использование версий Nt и Zw собственных процедур системных служб

ZwClose

ZwCommitComplete

ZwCommitEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenEnlistment

ZwOpenResourceManager

ZwOpenTransaction

ZwPrepareComplete

ZwPrePrepareEnlistment

ZwPrepareComplete

ZwPrepareEnlistment

ZwQueryInformationEnlistment

ZwReadOnlyEnlistment

ZwRecoverEnlistment

ZwRollbackComplete

ZwRollbackEnlistment

ZwSetInformationEnlistment

ZwSinglePhaseReject