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

Статья
08/08/2023

Подпрограмма ZwOpenKeyTransactedEx открывает существующий раздел реестра и связывает его с транзакцией.

Синтаксис

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

Параметры

[out] KeyHandle

Указатель на переменную HANDLE, в которую подпрограмма записывает дескриптор в ключ.

[in] DesiredAccess

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

[in] ObjectAttributes

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

[in] OpenOptions

Указывает параметры, применяемые при открытии ключа. Присвойте этому параметру значение ноль или побитовое ЗНАЧЕНИЕ ИЛИ одного или нескольких из следующих битов флага REG_OPTION_XXX .

Флаг OpenOptions	Описание
REG_OPTION_OPEN_LINK	Ключ является символьной ссылкой. Этот флаг не используется устройствами и промежуточными драйверами.
REG_OPTION_BACKUP_RESTORE	Ключ должен быть открыт с особыми привилегиями, разрешающими операции резервного копирования и восстановления. Этот флаг не используется устройствами и промежуточными драйверами.

[in] TransactionHandle

Дескриптор объекта транзакции. Чтобы получить этот дескриптор, можно вызвать подпрограмму ZwCreateTransaction . Или, если у вас есть указатель на объект транзакции, можно указать указатель на подпрограмму ObOpenObjectByPointer , чтобы получить соответствующий дескриптор транзакции.

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

ZwOpenKeyTransactedEx возвращает STATUS_SUCCESS, если вызов успешно открывает ключ. Возможные возвращаемые значения ошибок:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Параметр ObjectAttributes имеет значение NULL или указывает на недопустимые сведения.
STATUS_INVALID_PARAMETER_4	Значение параметра OpenOptions указывает недопустимые параметры.
STATUS_OBJECT_PATH_SYNTAX_BAD	Недопустимый путь реестра в атрибутах объекта.
STATUS_OBJECT_NAME_NOT_FOUND	Путь к реестру в атрибутах объекта не найден.
STATUS_ACCESS_DENIED	У вызывающего не было прав доступа, необходимых для открытия дескриптора именованного раздела реестра.
STATUS_INSUFFICIENT_RESOURCES	Сбой операции выделения памяти.

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

После того как дескриптор, на который указывает KeyHandle , больше не используется, драйвер должен вызвать подпрограмму ZwClose , чтобы закрыть ее.

Если указанный раздел не существует в реестре, ZwOpenKeyTransactedEx возвращает значение состояния ошибки и не предоставляет дескриптор ключа. В отличие от подпрограммы ZwCreateKeyTransacted , подпрограмма ZwOpenKeyTransactedEx не создает указанный ключ, если ключ не существует. И ZwCreateKeyTransacted , и ZwOpenKeyTransactedEx связывают раздел реестра с транзакцией.

Подпрограмма ZwOpenKeyEx похожа на ZwOpenKeyTransactedEx, но не связывает ключ с транзакцией.

Подпрограмма ZwOpenKeyTransacted аналогична процедуре ZwOpenKeyTransactedEx , но не принимает параметр OpenOptions . Параметр OpenOptionsобъекта ZwOpenKeyTransactedEx позволяет вызывающей объекту открыть ключ, представляющий собой символьную ссылку, или открыть ключ для операций резервного копирования и восстановления. Вызов ZwOpenKeyTransactedEx с параметром OpenOptions , равным нулю, эквивалентен вызову ZwOpenKeyTransacted.

После того как драйвер в режиме ядра получает дескриптор транзакции (например, путем вызова ZwCreateTransaction), драйвер может выполнять ряд операций с реестром, которые являются частью этой транзакции. Драйвер может закрыть транзакцию, зафиксировав изменения, внесенные в транзакцию, или откатив транзакцию.

После успешного завершения всех операций реестра, которые являются частью транзакции, драйвер может вызвать подпрограмму ZwCommitTransaction для фиксации изменений. Драйвер может вызвать подпрограмму ZwRollbackTransaction для отката транзакции.

Во время транзакции операция реестра является частью транзакции, если системный вызов, выполняющий операцию, соответствует одно из следующих условий:

Вызов задает в качестве входного параметра дескриптор транзакции. Например, вызовы ZwCreateKeyTransacted и ZwOpenKeyTransactedEx могут связать один или несколько ключей с транзакцией.
Вызов задает в качестве входного параметра дескриптор раздела реестра, полученный при вызове ZwCreateKeyTransacted или ZwOpenKeyTransactedEx , которому был предоставлен дескриптор транзакции. Например, при вызове подпрограммы ZwSetValueKey можно использовать дескриптор ключа, полученный таким образом, чтобы задать значение раздела реестра в рамках транзакции.

Дополнительные сведения о транзакциях в режиме ядра см. в разделе Использование диспетчера транзакций ядра.

ZwOpenKeyTransactedEx игнорирует сведения о безопасности в структуре, на которую указывает параметр ObjectAttributes .

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

Дополнительные сведения о работе с разделами реестра в режиме ядра см. в статье Использование реестра в драйвере.

Требования

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