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

Статья
08/08/2023

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

Синтаксис

NTSYSAPI NTSTATUS ZwCreateKeyTransacted(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [in]            HANDLE             TransactionHandle,
  [out, optional] PULONG             Disposition
);

Параметры

[out] KeyHandle

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

[in] DesiredAccess

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

[in] ObjectAttributes

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

TitleIndex

Драйверы устройств и промежуточных параметров задают для этого параметра нулевое значение.

[in, optional] Class

Драйверы устройства и промежуточные драйверы устанавливают для этого параметра значение NULL.

[in] CreateOptions

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

Флаг CreateOptions	Описание
REG_OPTION_VOLATILE	Ключ не сохраняется после перезагрузки компьютера.
REG_OPTION_NON_VOLATILE	Ключ сохраняется после перезагрузки компьютера.
REG_OPTION_CREATE_LINK	Ключ является символьной ссылкой. Этот флаг не используется драйверами устройств и промежуточными драйверами.
REG_OPTION_BACKUP_RESTORE	Откройте ключ со специальными привилегиями, которые позволяют выполнять операции резервного копирования и восстановления. Этот флаг не используется драйверами устройств и промежуточными драйверами.

[in] TransactionHandle

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

[out, optional] Disposition

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

Значение ликвидации	Описание
REG_CREATED_NEW_KEY	Создан новый ключ.
REG_OPENED_EXISTING_KEY	Был открыт существующий ключ.

Если эти сведения не требуются, можно задать для ликвидации = значение NULL .

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

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

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

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

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

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

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

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

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

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

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

Дескриптор безопасности в атрибутах объекта определяет, предоставляются ли права доступа, указанные в параметре DesiredAccess , при последующих вызовах подпрограмм, таких как ZwOpenKeyTransacted , которые обращаются к ключу, или подпрограмм, таких как ZwCreateKeyTransacted, создающих подразделы ключа.

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

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

Требования

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