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

Статья
12/21/2024

Подпрограмма 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.
В качестве имени пути относительно другого раздела реестра, представленного дескриптором в RootDirectory элемент входных ObjectAttributes.

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

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

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

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

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

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

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

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
правил соответствия DDI	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), Z, ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)