Função RegQueryValueA (winreg.h)

Artigo
08/27/2023

Recupera os dados associados ao valor padrão ou sem nome de uma chave do Registro especificada. Os dados devem ser uma cadeia de caracteres terminada em nulo.

Nota Essa função é fornecida apenas para compatibilidade com versões de 16 bits do Windows. Os aplicativos devem usar a função RegQueryValueEx .

Sintaxe

LSTATUS RegQueryValueA(
  [in]                HKEY   hKey,
  [in, optional]      LPCSTR lpSubKey,
  [out, optional]     LPSTR  lpData,
  [in, out, optional] PLONG  lpcbData
);

Parâmetros

[in] hKey

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

Esse identificador é retornado pela função RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx ou RegOpenKeyTransacted . Ela também pode ser uma das seguintes chaves predefinidas:

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_USERS

[in, optional] lpSubKey

O nome da subchave do parâmetro hKey para o qual o valor padrão é recuperado.

Os nomes de chave não diferenciam maiúsculas de minúsculas.

Se esse parâmetro for NULL ou apontar para uma cadeia de caracteres vazia, a função recuperará o valor padrão da chave identificada por hKey.

Para obter mais informações, consulte Limites de tamanho do elemento do Registro.

[out, optional] lpData

Um ponteiro para um buffer que recebe o valor padrão da chave especificada.

Se lpValue for NULL e lpcbValue for não NULL, a função retornará ERROR_SUCCESS e armazenará o tamanho dos dados, em bytes, na variável apontada por lpcbValue. Isso permite que um aplicativo determine a melhor maneira de alocar um buffer para os dados do valor.

[in, out, optional] lpcbData

Um ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro lpValue , em bytes. Quando a função retorna, essa variável contém o tamanho dos dados copiados para lpValue, incluindo quaisquer caracteres nulos de terminação.

Se os dados tiverem o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, esse tamanho incluirá caracteres ou caracteres nulos de terminação. Para obter mais informações, consulte Comentários.

Se o lpValue especificado pelo buffer não for grande o suficiente para manter os dados, a função retornará ERROR_MORE_DATA e armazenará o tamanho do buffer necessário na variável apontada por lpcbValue. Nesse caso, o conteúdo do buffer lpValue é indefinido.

Valor retornado

Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um código de erro do sistema.

Se o buffer lpValue for muito pequeno para receber o valor, a função retornará ERROR_MORE_DATA.

Comentários

Se a versão ANSI dessa função for usada (chamando explicitamente RegQueryValueA ou não definindo UNICODE antes de incluir o arquivo Windows.h), essa função converterá a cadeia de caracteres Unicode armazenada em uma cadeia de caracteres ANSI antes de copiá-la para o buffer especificado pelo parâmetro lpValue .

Se os dados tiverem o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, a cadeia de caracteres poderá não ter sido armazenada com os caracteres de terminação nula adequados. Portanto, mesmo que a função retorne ERROR_SUCCESS, o aplicativo deve garantir que a cadeia de caracteres seja encerrada corretamente antes de usá-la; caso contrário, ele pode substituir um buffer. (Observe que REG_MULTI_SZ cadeias de caracteres devem ter dois caracteres de terminação nula.)

Observe que as operações que acessam determinadas chaves do Registro são redirecionadas. Para obter mais informações, consulte Virtualização do Registro e Dados do Aplicativo de 32 bits e 64 bits no Registro.

Observação

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

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winreg.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll