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

Статья
02/27/2024

Подпрограмма ZwEnumerateKey возвращает сведения о подразделе открытого раздела реестра.

Синтаксис

NTSYSAPI NTSTATUS ZwEnumerateKey(
  [in]            HANDLE                KeyHandle,
  [in]            ULONG                 Index,
  [in]            KEY_INFORMATION_CLASS KeyInformationClass,
  [out, optional] PVOID                 KeyInformation,
  [in]            ULONG                 Length,
  [out]           PULONG                ResultLength
);

Параметры

[in] KeyHandle

Дескриптор раздела реестра, содержащего подразделы для перечисления. Дескриптор создается путем успешного вызова ZwCreateKey или ZwOpenKey.

[in] Index

Индекс подраздела, для которого требуется получить сведения. Если ключ содержит n подразделов, подразделы нумеруются от 0 до n-1.

[in] KeyInformationClass

Задает значение перечисления KEY_INFORMATION_CLASS , определяющее тип сведений, получаемых буфером KeyInformation . Задайте для параметра KeyInformationClass одно из следующих значений:

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

Если указано какое-либо значение, отсутствующее в этом списке, подпрограмма возвращает код ошибки STATUS_INVALID_PARAMETER.

[out, optional] KeyInformation

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

[in] Length

Задает размер буфера KeyInformation в байтах.

[out] ResultLength

Указатель на переменную, которая получает размер (в байтах) сведений о разделе реестра. Если ZwEnumerateKey возвращает STATUS_SUCCESS, можно использовать значение этой переменной для определения объема возвращаемых данных. Если подпрограмма возвращает STATUS_BUFFER_OVERFLOW или STATUS_BUFFER_TOO_SMALL, можно использовать значение этой переменной, чтобы определить размер буфера, необходимый для хранения сведений о ключе.

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

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

Код возврата	Описание
STATUS_BUFFER_OVERFLOW	Предоставленный буфер слишком мал, и в буфер были записаны только частичные данные. *Для параметра ResultLength задан минимальный размер, необходимый для хранения запрошенной информации.
STATUS_BUFFER_TOO_SMALL	Предоставленный буфер слишком мал, и данные не были записаны в буфер. *Для параметра ResultLength задан минимальный размер, необходимый для хранения запрошенной информации.
STATUS_INVALID_PARAMETER	Параметр KeyInformationClass не является допустимым KEY_INFORMATION_CLASS значением.
STATUS_NO_MORE_ENTRIES	Значение Index выходит за пределы диапазона для раздела реестра, указанного keyHandle. Например, если ключ содержит n подразделов, то для любого значения, превышающего n–1, подпрограмма возвращает STATUS_NO_MORE_ENTRIES.

Дескриптор должен быть открыт с KEY_ENUMERATE_SUB_KEYS доступом. Это достигается путем передачи KEY_ENUMERATE_SUB_KEYS, KEY_READ или KEY_ALL_ACCESS в качестве параметра DesiredAccess в ZwCreateKey или ZwOpenKey.

Параметр Index — это просто способ выбрать среди подразделов ключа, на который ссылается KeyHandle. Два вызова ZwEnumerateKey с одинаковым индексом не гарантированно возвращают одинаковый результат.

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

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

Для вызовов из драйверов режима ядра версии 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(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)