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

Статья
03/08/2023

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

Синтаксис

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

Параметры

[out] KeyHandle

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

[in] DesiredAccess

Задает значение ACCESS_MASK , определяющее запрошенный доступ к объекту. Помимо прав доступа, определенных для всех типов объектов (см. ACCESS_MASK), вызывающий объект может указать одно или несколько из следующих прав доступа, относящихся к каталогам объектов:

Флаг DesiredAccess	Позволяет вызывающей службе сделать это
KEY_QUERY_VALUE	Чтение значений ключей.
KEY_SET_VALUE	Запись значений ключа.
KEY_CREATE_SUB_KEY	Создайте подразделы для ключа.
KEY_ENUMERATE_SUB_KEYS	Чтение подразделов ключа.
KEY_CREATE_LINK	Создайте символьную ссылку на ключ. Этот флаг не используется устройствами и промежуточными драйверами.
KEY_NOTIFY	Попросите получать уведомление при изменении имени, значения или атрибутов ключа. Дополнительные сведения см. в разделе ZwNotifyChangeKey.

Вызывающий объект также может указать одну из следующих констант, которая объединяет несколько флагов ACCESS_MASK.

Константа	Состоит из этих флагов ACCESS_MASK
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS и KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE и KEY_CREATE_SUB_KEY
KEY_EXECUTE	То же, что и KEY_READ.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY и KEY_CREATE_LINK

[in] ObjectAttributes

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

TitleIndex

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

[in, optional] Class

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

[in] CreateOptions

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

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

[out, optional] Disposition

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

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

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

ZwCreateKey возвращает STATUS_SUCCESS при успешном выполнении или соответствующий код ошибки NTSTATUS при сбое.

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

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

Существует два альтернативных способа указать имя файла, который будет создан или открыт с помощью ZwCreateKey:

В виде полного имени пути, указанного в элементе ObjectName входных атрибутов ObjectAttributes. Путь к разделам реестра начинается с \Registry.
В качестве pathname относительно другого раздела реестра, представленного дескриптором в элементе RootDirectory входного объекта ObjectAttributes.

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

Если указанный ключ уже существует, он открывается и его значение никак не влияет.

Атрибуты безопасности, заданные ObjectAttributes при создании ключа, определяют, предоставляется ли указанный элемент DesiredAccess при последующих вызовах ZwCreateKey и ZwOpenKey.

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

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

Если вызов этой функции выполняется в пользовательском режиме, следует использовать имя NtCreateKey вместо ZwCreateKey.

Подпрограмма NtCreateKey в ядре Windows недоступна напрямую для драйверов режима ядра.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы Собственные системные службы Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.

Требования

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