Função RegQueryValueExA (winreg.h)

Recupera o tipo e os dados do nome do valor especificado associado a uma chave do Registro aberta.

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);
}

Requisitos

Confira também

ExpandEnvironmentStrings

RegCreateKeyEx

RegEnumKeyEx

RegEnumValue

RegGetValue

RegOpenKeyEx

RegQueryInfoKey

Funções do Registro

Visão geral do Registro