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

Статья
08/08/2023

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

Синтаксис

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

Параметры

[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	Ключ должен быть открыт с особыми привилегиями, которые разрешают операции резервного копирования и восстановления. Этот флаг не используется драйверами устройств и промежуточными драйверами.

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

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

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

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

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

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

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

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

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

Требования

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

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

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ZwClose

ZwOpenKey