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

Статья
03/14/2023

Подпрограмма ZwCreateTransaction создает объект транзакции.

Синтаксис

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Параметры

[out] TransactionHandle

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

[in] DesiredAccess

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

Маска доступа	Разрешает вызывающей
TRANSACTION_COMMIT	Зафиксируйте транзакцию (см. ZwCommitTransaction).
TRANSACTION_ENLIST	Создайте зачисление для транзакции (см. ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Не используйте.
TRANSACTION_QUERY_INFORMATION	Получите сведения о транзакции (см. ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Откат транзакции (см. ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Задайте сведения для транзакции (см. ZwSetInformationTransaction).

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

Точечный рисунок прав	Набор определенных прав доступа
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION и SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT и SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK и SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE и TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE и SYNCHRONIZE

Как правило, диспетчер ресурсов задает TRANSACTION_RESOURCE_MANAGER_RIGHTS.

Значение DesiredAccess не может быть равным нулю.

[in, optional] ObjectAttributes

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

[in, optional] Uow

Указатель на GUID, который KTM использует в качестве идентификатора единицы работы (UOW) нового объекта транзакции. Этот параметр является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, KTM создает GUID и назначает его объекту транзакции. Дополнительные сведения см. в разделе "Примечания".

[in, optional] TmHandle

Дескриптор объекта диспетчера транзакций , полученный при предыдущем вызове ZwCreateTransactionManager или ZwOpenTransactionManager. KTM назначает новый объект транзакции указанному объекту диспетчера транзакций. Если этот параметр имеет значение NULL, KTM назначает новый объект транзакции диспетчеру транзакций позже, когда диспетчер ресурсов создает зачисление для транзакции.

[in, optional] CreateOptions

Необязательные флаги создания объектов. В следующей таблице содержатся доступные флаги, определенные в Ktmtypes.h.

Флаг параметра	Значение
TRANSACTION_DO_NOT_PROMOTE	Зарезервировано для будущего использования.

[in, optional] IsolationLevel

Зарезервировано для будущего использования. Вызывающие абоненты должны задать для этого параметра нулевое значение.

[in, optional] IsolationFlags

Зарезервировано для последующего использования. Вызывающие абоненты должны задать для этого параметра нулевое значение.

[in, optional] Timeout

Указатель на значение времени ожидания. Если транзакция не была зафиксирована к времени, указанному в этом параметре, KTM выполняет откат транзакции. Значение времени ожидания выражается в единицах системного времени (100-наносекундные интервалы) и может указывать как абсолютное, так и относительное время. Если значение, указанное в параметре Timeout , отрицательное, время окончания срока действия будет относительно текущего системного времени. В противном случае время окончания срока действия будет абсолютным. Этот указатель является необязательным и может иметь значение NULL , если вы не хотите, чтобы у транзакции было время ожидания. Если время ожидания = РАВНО NULL или *Время ожидания = 0, время ожидания транзакции никогда не истекает. (Вы также можете использовать ZwSetInformationTransaction , чтобы задать значение времени ожидания.)

[in, optional] Description

Указатель на структуру, предоставляемую вызывающим UNICODE_STRING , которая содержит строку, завершающуюся значением NULL. Строка предоставляет описание транзакции. KTM сохраняет копию строки и включает ее в сообщения, записываемые в поток журнала. Максимальная длина строки — MAX_TRANSACTION_DESCRIPTION_LENGTH. Этот параметр является необязательным и может иметь значение NULL.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Параметр CreateOptions содержит недопустимый флаг, параметр DesiredAccess равен нулю или строка параметра Description слишком длинна.
STATUS_INSUFFICIENT_RESOURCES	KTM не удалось выделить системные ресурсы (обычно это память).
STATUS_INVALID_ACL	Дескриптор безопасности содержит недопустимый список управления доступом (ACL).
STATUS_INVALID_SID	Дескриптор безопасности содержит недопустимый идентификатор безопасности (SID).
STATUS_OBJECT_NAME_EXISTS	Имя объекта, указанное параметром ObjectAttributes , уже существует.
STATUS_OBJECT_NAME_INVALID	Недопустимое имя объекта, указанное в параметре ObjectAttributes .
STATUS_ACCESS_DENIED	Недопустимое значение параметра DesiredAccess .

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

Вызывающий объект может использовать параметр Uow , чтобы указать идентификатор UOW для объекта транзакции. Если вызывающий объект не указывает идентификатор UOW, KTM создает GUID и назначает его объекту транзакции. Позже вызывающий объект может получить этот GUID, вызвав ZwQueryInformationTransaction.

Как правило, необходимо разрешить KTM создать GUID для объекта транзакции, если компонент не взаимодействует с другим компонентом TPS, который уже создал идентификатор UOW для транзакции.

Чтобы закрыть дескриптор транзакции, компонент, который вызвал ZwCreateTransaction , должен вызвать ZwClose. Если дескриптор последней транзакции закрывается до того, как какой-либо компонент вызывает ZwCommitTransaction для транзакции, KTM откатывает транзакцию.

Дополнительные сведения о том, как клиенты транзакций должны использовать ZwCreateTransaction, см. в разделе Создание транзакционного клиента.

Для вызовов из драйверов режима ядра версии 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	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)