Função RegQueryMultipleValuesW (winreg.h)

Artigo
11/20/2024

Recupera o tipo e os dados de uma lista de nomes de valor associados a uma chave aberta do Registro.

Sintaxe

LSTATUS RegQueryMultipleValuesW(
  [in]                HKEY     hKey,
  [out]               PVALENTW val_list,
  [in]                DWORD    num_vals,
  [out, optional]     LPWSTR   lpValueBuf,
  [in, out, optional] LPDWORD  ldwTotsize
);

Parâmetros

[in] hKey

Um identificador para uma chave aberta do Registro. A chave deve ter sido aberta com o acesso KEY_QUERY_VALUE direito. Para obter mais informações, consulte de Direitos de Acesso e Segurança de Chave do Registro.

Esse identificador é retornado pelo RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyExou função regOpenKeyTransacted. Também pode ser uma das seguintes chaves predefinidas :

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[out] val_list

Um ponteiro para uma matriz de estruturas VALENT que descrevem uma ou mais entradas de valor. Na entrada, o membro ve_valuename de cada estrutura deve conter um ponteiro para o nome de um valor a ser recuperado. A função falhará se algum dos valores especificados não existir na chave especificada.

Se a função for bem-sucedida, cada elemento da matriz conterá as informações do valor especificado.

[in] num_vals

O número de elementos na matriz val_list.

[out, optional] lpValueBuf

Um ponteiro para um buffer. Se a função for bem-sucedida, o buffer receberá os dados de cada valor.

Se lpValueBuf for NULL, o valor apontado pelo parâmetro ldwTotsize do deverá ser zero; nesse caso, a função retorna ERROR_MORE_DATA e ldwTotsize recebe o tamanho necessário do buffer, em bytes.

[in, out, optional] ldwTotsize

Um ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro lpValueBuf, em bytes. Se a função for bem-sucedida, ldwTotsize receberá o número de bytes copiados para o buffer. Se a função falhar porque o buffer é muito pequeno, ldwTotsize recebe o tamanho necessário, em bytes.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_CANTREAD	RegQueryMultipleValues não pode criar uma instância ou acessar o provedor da chave dinâmica.
ERROR_MORE_DATA	O buffer apontado por lpValueBuf era muito pequeno. Nesse caso, ldwTotsize recebe o tamanho do buffer necessário.
ERROR_TRANSFER_TOO_LONG	O tamanho total dos dados solicitados (tamanho da matriz val_list + ldwTotSize) é maior que o limite do sistema de um megabyte.

Observações

A função RegQueryMultipleValues permite que um aplicativo consulte um ou mais valores de uma chave estática ou dinâmica. Se a chave de destino for uma chave estática, o sistema fornecerá todos os valores de forma atômica. Para evitar serialização excessiva, os dados agregados retornados pela função não podem exceder um megabyte.

Se a chave de destino for uma chave dinâmica, seu provedor deverá fornecer todos os valores de forma atômica. Isso significa que o provedor deve preencher o buffer de resultados de forma síncrona, fornecendo uma exibição consistente de todos os valores no buffer, evitando a serialização excessiva. O provedor pode fornecer no máximo um megabyte de dados de saída total durante uma chamada atômica para essa função.

RegQueryMultipleValues tem suporte remoto; ou seja, o parâmetro hKey passado para a função pode se referir a um computador remoto.

Nota

O cabeçalho winreg.h define RegQueryMultipleValues como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winreg.h (inclua Windows.h)
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Consulte também

Funções do Registro

Visão geral do Registro

VALENT

Compartilhar via