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 tem garantia de ser 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 KEY_QUERY_VALUE direito de acesso. 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 . 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 só poderá ser NULL se lpData for NULL.
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, a menos que os dados sejam armazenados sem eles. Para obter mais informações, consulte Comentários.
Se o buffer especificado pelo 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 lpData é indefinido.
Se lpData for NULL e lpcbData não for NULL, 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 hKeyespecificar HKEY_PERFORMANCE_DATA e o buffer lpData não for grande o suficiente para conter todos os dados retornados, RegQueryValueEx retornará ERROR_MORE_DATA e o valor retornado por meio do parâmetro lpcbData será indefinido. Isso ocorre porque o tamanho dos dados de desempenho pode mudar de uma chamada para outra. Nesse caso, você deve aumentar o tamanho do buffer e chamar RegQueryValueEx novamente passando o tamanho do buffer atualizado no parâmetro lpcbData . Repita isso até que a função seja bem-sucedida. Você precisa manter uma variável separada para controlar o tamanho do buffer, pois o valor retornado por lpcbData é imprevisível.
Se o valor do registro lpValueName não existir, RegQueryValueEx retornará ERROR_FILE_NOT_FOUND e o valor retornado por meio do parâmetro lpcbData será indefinido.
Retornar valor
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 lpData for muito pequeno para receber os dados, a função retornará ERROR_MORE_DATA.
Se o valor do registro lpValueName não existir, a função retornará ERROR_FILE_NOT_FOUND.
Comentários
Um aplicativo normalmente chama RegEnumValue para determinar os nomes de valor e RegQueryValueEx para recuperar os dados dos nomes.
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 nulos de terminação 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 REG_MULTI_SZ cadeias de caracteres devem ter dois caracteres nulos de terminação.) Uma maneira de um aplicativo garantir que a cadeia de caracteres seja terminada corretamente é usar RegGetValue, que adiciona caracteres nulos de terminação, se necessário.
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 Virtualização do Registro e Dados do 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);
}
Observação
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 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 |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de