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

Статья
02/07/2025

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

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Параметры

[out] TmHandle

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

[in] DesiredAccess

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

флаг ACCESS_MASK	Разрешает вызывающую функцию
TRANSACTIONMANAGER_CREATE_RM	Создание диспетчера ресурсов (см. ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Получите сведения о диспетчере транзакций (см. ZwQueryInformationTransactionManager и ZwEnumerateTransactionObject). Также требуется для ZwOpenResourceManager, ZwCreateTransactionи ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Восстановите диспетчер транзакций (см. ZwRecoverTransactionManager и ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Не используется.
TRANSACTIONMANAGER_SET_INFORMATION	Не используется.

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

Растровое изображение прав	Набор определенных прав доступа
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ и TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME и TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE и TRANSACTIONMANAGER_GENERIC_EXECUTE

[in, optional] ObjectAttributes

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

[in, optional] LogFileName

Указатель на структуру UNICODE_STRING, содержащую путь и имя файла потока файлов журнала CLFS, связанного с объектом диспетчера транзакций. Этот параметр должен быть NULL, если параметр createOptions TRANSACTION_MANAGER_VOLATILE. В противном случае этот параметр должен быть неNULL. Дополнительные сведения см. в следующем разделе "Примечания".

[in, optional] CreateOptions

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

Флаг параметра	Значение
TRANSACTION_MANAGER_VOLATILE	Объект диспетчера транзакций будет переменным. Поэтому он не будет использовать файл журнала.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Только для внутреннего использования.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Только для внутреннего использования.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Только для внутреннего использования.
TRANSACTION_MANAGER_COMMIT_LOWEST	Только для внутреннего использования.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Только для внутреннего использования.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Только для внутреннего использования.

[in, optional] CommitStrength

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

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

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

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

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

Замечания

Если поток файлов журнала, который указывает параметр logFileName , не существует, KTM вызывает CLFS для создания потока. Если поток уже существует, KTM вызывает CLFS для открытия потока.

Компонент TPS должен вызывать ZwRecoverTransactionManager после вызова ZwCreateTransactionManager

Если компонент TPS задает флаг TRANSACTION_MANAGER_VOLATILE в параметре CreateOptions , все диспетчеры ресурсов, связанные с объектом диспетчера транзакций, должны указать флаг RESOURCE_MANAGER_VOLATILE при вызове ZwCreateResourceManager.

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

Дополнительные сведения об использовании ZwCreateTransactionManagerсм. в созданииResource Manager.

NtCreateTransactionManager и ZwCreateTransactionManager являются двумя версиями одной подпрограммы windows Native System Services.

Для вызовов драйверов в режиме ядра 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, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDDIs, PowerIrpDDis