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

Статья
02/07/2025

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [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 и СИНХРОНИЗАЦИЯ
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT и СИНХРОНИЗАЦИЯ
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK и СИНХРОНИЗИРОВАТЬ
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 и СИНХРОНИЗАЦИЯ

Как правило, диспетчер ресурсов задает 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-наносекундных интервалов) и может указывать абсолютное время или относительное время. Если значение, на которое указывает время ожидания , отрицательное, время истечения срока действия относительно текущего системного времени. В противном случае срок действия является абсолютным. Этот указатель необязателен и может быть null, если у транзакции нет значения времени ожидания. Если время ожидания = NULL или *время ожидания = 0, транзакция никогда не истекает. (Можно также использовать ZwSetInformationTransaction для задания значения времени ожидания.)

[in, optional] Description

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

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

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

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Параметр CreateOptions содержит недопустимый флаг, параметр DesiredAccess равен нулю, или строка описания параметра слишком длинна.
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 Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно в Windows Vista и более поздних версиях операционной системы.
целевая платформа	Всеобщий
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDDIs, PowerIrpDDis