Função ZwEnumerateKey (wdm.h)

Artigo
02/27/2024

A rotina ZwEnumerateKey retorna informações sobre uma subchave de uma chave do Registro aberta.

Sintaxe

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

Parâmetros

[in] KeyHandle

Manipule para a chave do Registro que contém as subchaves a serem enumeradas. O identificador é criado por uma chamada bem-sucedida para ZwCreateKey ou ZwOpenKey.

[in] Index

O índice da subchave para a qual você deseja obter informações. Se a chave tiver n subchaves, as subchaves serão numeradas de 0 a n-1.

[in] KeyInformationClass

Especifica um valor de enumeração KEY_INFORMATION_CLASS que determina o tipo de informação a ser recebida pelo buffer KeyInformation . Defina KeyInformationClass como um dos seguintes valores:

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

Se qualquer valor não estiver nessa lista for especificado, a rotina retornará o código de erro STATUS_INVALID_PARAMETER.

[out, optional] KeyInformation

Ponteiro para um buffer alocado pelo chamador que recebe as informações solicitadas. O parâmetro KeyInformationClass determina o tipo de informação fornecida.

[in] Length

Especifica o tamanho, em bytes, do buffer KeyInformation .

[out] ResultLength

Ponteiro para uma variável que recebe o tamanho, em bytes, das informações de chave do Registro. Se ZwEnumerateKey retornar STATUS_SUCCESS, você poderá usar o valor dessa variável para determinar a quantidade de dados retornados. Se a rotina retornar STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL, você poderá usar o valor dessa variável para determinar o tamanho do buffer necessário para manter as informações de chave.

Retornar valor

ZwEnumerateKey retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado em caso de falha. Os possíveis valores de código de erro incluem:

Código de retorno	Descrição
STATUS_BUFFER_OVERFLOW	O buffer fornecido é muito pequeno e apenas os dados parciais foram gravados no buffer. *ResultLength é definido como o tamanho mínimo necessário para manter as informações solicitadas.
STATUS_BUFFER_TOO_SMALL	O buffer fornecido é muito pequeno e nenhum dado foi gravado no buffer. *ResultLength é definido como o tamanho mínimo necessário para manter as informações solicitadas.
STATUS_INVALID_PARAMETER	O parâmetro KeyInformationClass não é um valor KEY_INFORMATION_CLASS válido.
STATUS_NO_MORE_ENTRIES	O valor index está fora do intervalo para a chave do Registro especificada por KeyHandle. Por exemplo, se uma chave tiver n subchaves, para qualquer valor maior que n-1, a rotina retornará STATUS_NO_MORE_ENTRIES.

Comentários

O identificador deve ter sido aberto com acesso KEY_ENUMERATE_SUB_KEYS. Isso é feito passando KEY_ENUMERATE_SUB_KEYS, KEY_READ ou KEY_ALL_ACCESS como o parâmetro DesiredAccess para ZwCreateKey ou ZwOpenKey.

O parâmetro Index é simplesmente uma maneira de selecionar entre subchaves da chave referenciada pelo KeyHandle. Não há garantia de que duas chamadas para ZwEnumerateKey com o mesmo Índice retornem o mesmo resultado.

Para obter mais informações sobre como trabalhar com chaves do Registro, consulte Usando o Registro em um Driver.

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtEnumerateKey" em vez de "ZwEnumerateKey".

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)