Função RegQueryValueExA (winreg.h)
Recupera o tipo e os dados do nome do valor especificado associado a uma chave do Registro aberta.
Aviso
Se o valor que está sendo consultado for uma cadeia de caracteres (REG_SZ, REG_MULTI_SZ e REG_EXPAND_SZ), o valor retornado NÃO será garantido como encerrado em nulo. Use a função RegGetValue se quiser garantir que os valores de cadeia de caracteres retornados sejam encerrados em nulo. Mais informações estão nas observações abaixo.
Sintaxe
LSTATUS RegQueryValueExA(
[in] HKEY hKey,
[in, optional] LPCSTR lpValueName,
LPDWORD lpReserved,
[out, optional] LPDWORD lpType,
[out, optional] LPBYTE lpData,
[in, out, optional] LPDWORD lpcbData
);
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_PERFORMANCE_NLSTEXT
- HKEY_PERFORMANCE_TEXT
- HKEY_USERS
[in, optional] lpValueName
O nome do valor do registro.
Se lpValueName for NULL ou uma cadeia de caracteres vazia, "", a função recuperará o tipo e os dados do valor não nomeado ou padrão da chave, se houver.
Se lpValueName especificar um valor que não está no registro, a função retornará ERROR_FILE_NOT_FOUND.
As chaves não têm automaticamente um valor não nomeado ou padrão. Valores sem nome podem ser de qualquer tipo. Para obter mais informações, consulte limites de tamanho do elemento do Registro.
lpReserved
Esse parâmetro é reservado e deve ser NULL.
[out, optional] lpType
Um ponteiro para uma variável que recebe um código que indica o tipo de dados armazenados no valor especificado. Para obter uma lista dos códigos de tipo possíveis, consulte Tipos de Valor do Registro. O parâmetro lpType poderá ser NULL se o código de tipo não for necessário.
[out, optional] lpData
Um ponteiro para um buffer que recebe os dados do valor. Esse parâmetro poderá ser NULL se os dados não forem necessários.
[in, out, optional] lpcbData
Um ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro lpData, em bytes. Quando a função retorna, essa variável contém o tamanho dos dados copiados para lpData.
O parâmetro lpcbData poderá ser NULL somente se lpData estiver NULL.
Se os dados tiverem o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, esse tamanho incluirá qualquer terminação caracteres ou caracteres nulos, a menos que os dados sejam armazenados sem eles. Para obter mais informações, consulte Comentários.
Se o buffer especificado por parâmetro lpData 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 lpcbData. Nesse caso, o conteúdo do buffer de lpData é indefinido.
Se lpData for NULL e lpcbData não forNULL, a função retornará ERROR_SUCCESS e armazenará o tamanho dos dados, em bytes, na variável apontada por lpcbData. Isso permite que um aplicativo determine a melhor maneira de alocar um buffer para os dados do valor.
Se
Se o lpValueName valor do registro não existir, RegQueryValueEx retornará ERROR_FILE_NOT_FOUND e o valor retornado por meio do parâmetro lpcbData será indefinido.
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 código de erro do sistema.
Se o buffer lpData for muito pequeno para receber os dados, a função retornará ERROR_MORE_DATA.
Se o lpValueName valor do Registro não existir, a função retornará ERROR_FILE_NOT_FOUND.
Observações
Um aplicativo normalmente chama RegEnumValue para determinar os nomes de valor e, em seguida, RegQueryValueEx para recuperar os dados dos nomes.
Se os dados tiverem o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, talvez a cadeia de caracteres não tenha sido armazenada com os caracteres de nulos adequados. Portanto, mesmo que a função retorne ERROR_SUCCESS, o aplicativo deve garantir que a cadeia de caracteres seja terminada corretamente antes de usá-la; caso contrário, ele pode substituir um buffer. (Observe que as cadeias de caracteres de REG_MULTI_SZ devem ter dois caracteres de nulos
Se os dados tiverem o tipo REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ e a versão ANSI dessa função for usada (chamando explicitamente RegQueryValueExA 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 apontado por lpData.
Ao chamar a função RegQueryValueEx com hKey definido como o identificador HKEY_PERFORMANCE_DATA e uma cadeia de caracteres de valor de um objeto especificado, a estrutura de dados retornada às vezes tem objetos não solicitados. Não se surpreenda; esse é um comportamento normal. Ao chamar a função RegQueryValueEx, você sempre deve esperar percorrer a estrutura de dados retornada para procurar o objeto solicitado.
Observe que as operações que acessam determinadas chaves do Registro são redirecionadas. Para obter mais informações, consulte de Virtualização do Registro e dados de aplicativo de 32 bits e 64 bits no Registro.
Exemplos
Verifique se você reinicializa o valor apontado pelo parâmetro lpcbData sempre que chamar essa função. Isso é muito importante quando você chama essa função em um loop, como no exemplo de código a seguir.
#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#define TOTALBYTES 8192
#define BYTEINCREMENT 4096
void main()
{
DWORD BufferSize = TOTALBYTES;
DWORD cbData;
DWORD dwRet;
PPERF_DATA_BLOCK PerfData = (PPERF_DATA_BLOCK) malloc( BufferSize );
cbData = BufferSize;
printf("\nRetrieving the data...");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
while( dwRet == ERROR_MORE_DATA )
{
// Get a buffer that is big enough.
BufferSize += BYTEINCREMENT;
PerfData = (PPERF_DATA_BLOCK) realloc( PerfData, BufferSize );
cbData = BufferSize;
printf(".");
dwRet = RegQueryValueEx( HKEY_PERFORMANCE_DATA,
TEXT("Global"),
NULL,
NULL,
(LPBYTE) PerfData,
&cbData );
}
if( dwRet == ERROR_SUCCESS )
printf("\n\nFinal buffer size is %d\n", BufferSize);
else printf("\nRegQueryValueEx failed (%d)\n", dwRet);
}
Nota
O cabeçalho winreg.h define RegQueryValueEx 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
RegCreateKeyEx
RegOpenKeyEx