Поделиться через


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

Подпрограмма 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)

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

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObOpenObjectByPointer

ZwClose

ZwCommitTransaction

ZwCreateKey

ZwCreateKeyTransacted

ZwCreateTransaction

ZwOpenKeyEx

ZwOpenKeyTransacted

ZwRollbackTransaction

ZwSetValueKey