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

Artigo
02/26/2024

O QueryValueKey método recupera informações sobre as entradas de valor de uma chave do Registro, incluindo seus nomes, tipos, tamanhos de dados e valores.

Sintaxe

NTSTATUS QueryValueKey(
  [in]  PUNICODE_STRING             ValueName,
  [in]  KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
  [out] PVOID                       KeyValueInformation,
  [in]  ULONG                       Length,
  [out] PULONG                      ResultLength
);

Parâmetros

[in] ValueName

Ponteiro para o nome fornecido pelo fabricante da entrada de valor. A cadeia de caracteres de nome é especificada por uma estrutura do tipo UNICODE_STRING.

[in] KeyValueInformationClass

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

KeyValueBasicInformation
KeyValueFullInformation
KeyValuePartialInformation

[out] KeyValueInformation

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_VALUE_BASIC_INFORMATION, KEY_VALUE_FULL_INFORMATION ou KEY_VALUE_PARTIAL_INFORMATION, dependendo do valor de KeyValueInformationClass. A estrutura é seguida por dados adicionais cujo tamanho depende do tipo de dados do valor da chave.

[in] Length

Tamanho em bytes do buffer KeyValueInformation , que o chamador deve definir de acordo com o KeyValueInformationClass fornecido. 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 pelo chamador na qual o método grava uma contagem especificando o número de bytes realmente gravados no buffer KeyValueInformation . Se o tamanho 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.

Retornar valor

QueryValueKey retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida na cópia das informações solicitadas para o buffer KeyValueInformation . 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 erro apropriado status código. 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.
STATUS_OBJECT_NAME_NOT_FOUND	Indica que a entrada de valor com o nome especificado não foi encontrada.

Comentários

Se o buffer KeyValueInformation for muito pequeno para manter as informações solicitadas, o método gravará o tamanho necessário em *ResultLength e retornará um código status de STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL. O método retornará STATUS_BUFFER_OVERFLOW se tiver êxito em 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 manter todas as informações solicitadas.