Função ZwQueryKey (wdm.h)

Artigo
08/08/2023

A rotina ZwQueryKey fornece informações sobre a classe de uma chave do Registro e o número e os tamanhos de suas subchaves.

Sintaxe

NTSYSAPI NTSTATUS ZwQueryKey(
  [in]            HANDLE                KeyHandle,
  [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 sobre a qual obter informações. Esse identificador é criado por uma chamada bem-sucedida para ZwCreateKey ou ZwOpenKey.

[in] KeyInformationClass

Especifica um valor KEY_INFORMATION_CLASS que determina o tipo de informação retornado no buffer KeyInformation .

[out, optional] KeyInformation

Ponteiro para um buffer alocado pelo chamador que recebe as informações solicitadas.

[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 solicitadas. Se ZwQueryKey retornar STATUS_SUCCESS, a variável conterá a quantidade de dados retornados. Se ZwQueryKey retornar STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL, você poderá usar o valor da variável para determinar o tamanho do buffer necessário.

Retornar valor

ZwQueryKey retorna STATUS_SUCCESS em caso de êxito ou o código de erro 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 de KEY_INFORMATION_CLASS válido.

Comentários

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

Se KeyInformationClass for KeyNameInformation ou KeyHandleTagsInformation, o requisito de KEY_QUERY_VALUE não se aplicará.

ZwQueryKey pode ser usado para obter informações que você pode usar para alocar buffers para armazenar dados do Registro, como o tamanho máximo de entradas de valor de uma chave ou nomes de subchaves ou o número de subchaves. Por exemplo, você pode chamar ZwQueryKey, usar as informações retornadas para alocar um buffer para uma subchave, chamar ZwEnumerateKey para obter o nome da subchave e passar esse nome para uma rotina do RegistroRtlXxx.

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 "NtQueryKey" em vez de "ZwQueryKey".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services 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 Using Nt and Zw Versions of the Native System Services Routines.

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 da DDI	HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(storport), ZwRegistryOpen(storport), ZwRegistryOpen(wdm)