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

Подпрограмма 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), вызывающий объект может указать любой из следующих флагов для объектов транзакций.

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

Как правило, диспетчер ресурсов задает 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.

[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, если операция выполнена успешно. В противном случае эта подпрограмма может возвращать одно из следующих значений:

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

Комментарии

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

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

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

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

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

Требования

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

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

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

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction