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

Статья
08/08/2023

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

Синтаксис

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

Параметры

[out] KeyHandle

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

[in] DesiredAccess

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

[in] ObjectAttributes

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

[in] TransactionHandle

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

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