Método IRegistryKey::QueryKey (portcls.h)

Artigo
02/07/2025

O método QueryKey recupera informações sobre uma chave do Registro, incluindo o nome da chave, a classe de chave e o número de subchaves e seus tamanhos.

Sintaxe

NTSTATUS QueryKey(
  [in]  KEY_INFORMATION_CLASS KeyInformationClass,
  [out] PVOID                 KeyInformation,
  [in]  ULONG                 Length,
  [out] PULONG                ResultLength
);

Parâmetros

[in] KeyInformationClass

Especifica o tipo de informação a ser retornado no buffer. Defina esse parâmetro como um dos seguintes valores de enumeração KEY_INFORMATION_CLASS:

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

[out] KeyInformation

Ponteiro para um buffer alocado pelo chamador no qual o método grava os dados solicitados. O buffer contém uma estrutura do tipo KEY_BASIC_INFORMATION, KEY_FULL_INFORMATIONou KEY_NODE_INFORMATION, dependendo do valor de KeyInformationClass. A estrutura é seguida por uma cadeia de caracteres Unicode cujo tamanho depende do tipo de informação solicitada sobre a chave e o comprimento do nome da chave ou da cadeia de caracteres de classe.

[in] Length

Tamanho em bytes do buffer KeyInformation, que o chamador deve definir de acordo com o KeyInformationClassfornecido. Para receber todos os dados solicitados, o buffer deve ser pelo menos tão grande quanto o tamanho dos dados solicitados.

[out] ResultLength

Ponteiro de saída para o comprimento dos dados resultantes. Esse parâmetro aponta para uma variável ULONG alocada por chamador na qual o método grava uma contagem especificando o número de bytes realmente gravados no buffer KeyInformation. Se o comprimento do buffer especificado for muito pequeno para conter as informações, no entanto, o método gerará o tamanho do buffer necessário e retornará STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

QueryKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida na cópia das informações solicitadas para o buffer KeyInformation. Se o tamanho do buffer especificado for muito pequeno para receber todas as informações solicitadas, o método retornará STATUS_BUFFER_OVERFLOW. Se o tamanho do buffer especificado for muito pequeno para receber qualquer uma das informações solicitadas, o método retornará STATUS_BUFFER_TOO_SMALL. Caso contrário, o método retornará um código de status de erro apropriado. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Indica que um dos parâmetros passados para o método não é válido.

Observações

Se o buffer KeyInformation for muito pequeno para armazenar as informações solicitadas, o método gravará o tamanho necessário para * ResultLength e retornará um código de status de STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL. O método retornará STATUS_BUFFER_OVERFLOW se tiver êxito ao gravar apenas parte das informações solicitadas no buffer. O método retornará STATUS_BUFFER_TOO_SMALL se não for possível gravar nenhuma informação no buffer. O valor gravado em * ResultLength indica o tamanho mínimo do buffer necessário para armazenar todas as informações solicitadas.