Função RegGetValueA (winreg.h)
Recupera o tipo e os dados do valor do Registro especificado.
Sintaxe
LSTATUS RegGetValueA(
[in] HKEY hkey,
[in, optional] LPCSTR lpSubKey,
[in, optional] LPCSTR lpValue,
[in, optional] DWORD dwFlags,
[out, optional] LPDWORD pdwType,
[out, optional] PVOID pvData,
[in, out, optional] LPDWORD pcbData
);
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] lpSubKey
O caminho de uma chave do Registro em relação à chave especificada pelo parâmetro hkey . O valor do Registro será recuperado dessa subchave.
O caminho não diferencia maiúsculas de minúsculas.
Se esse parâmetro for NULL ou uma cadeia de caracteres vazia, "", o valor será lido da chave especificada pelo próprio hkey .
[in, optional] lpValue
O nome do valor do Registro.
Se esse parâmetro 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. As chaves não têm automaticamente um valor não nomeado ou padrão e os valores não nomeados podem ser de qualquer tipo.
Para obter mais informações, consulte Limites de tamanho do elemento do Registro.
[in, optional] dwFlags
Os sinalizadores que restringem o tipo de dados de valor a ser consultado. Se o tipo de dados do valor não atender a esses critérios, a função falhará. Esse parâmetro pode usar um dos valores a seguir.
Esse parâmetro também pode incluir um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Não expanda automaticamente as cadeias de caracteres de ambiente se o valor for do tipo REG_EXPAND_SZ. |
|
Se pvData não for NULL, defina o conteúdo do buffer como zeros em caso de falha. |
|
Se lpSubKey não for NULL, abra a subchave que lpSubKey especifica com os direitos de acesso KEY_WOW64_64KEY.
Para obter informações sobre esses direitos de acesso, consulte Segurança de Chave do Registro e Direitos de Acesso.
Não é possível especificar RRF_SUBKEY_WOW6464KEY em combinação com RRF_SUBKEY_WOW6432KEY. |
|
Se lpSubKey não for NULL, abra a subchave que lpSubKey especifica com os direitos de acesso KEY_WOW64_32KEY.
Para obter informações sobre esses direitos de acesso, consulte Segurança de Chave do Registro e Direitos de Acesso.
Não é possível especificar RRF_SUBKEY_WOW6432KEY em combinação com RRF_SUBKEY_WOW6464KEY. |
[out, optional] pdwType
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. Esse parâmetro poderá ser NULL se o tipo não for necessário.
[out, optional] pvData
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.
Se os dados forem uma cadeia de caracteres, a função verificará se há um caractere nulo de terminação. Se um não for encontrado, a cadeia de caracteres será armazenada com um terminador nulo se o buffer for grande o suficiente para acomodar o caractere extra. Caso contrário, a função falhará e retornará ERROR_MORE_DATA.
[in, out, optional] pcbData
Um ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro pvData , em bytes. Quando a função retorna, essa variável contém o tamanho dos dados copiados para pvData.
O parâmetro pcbData só poderá ser NULL se pvData 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. Para obter mais informações, consulte Comentários.
Se o buffer especificado pelo parâmetro pvData 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 pcbData. Nesse caso, o conteúdo do buffer pvData será zero se dwFlags especificar RRF_ZEROONFAILURE e indefinido de outra forma.
Se pvData for NULL e pcbData não for NULL, a função retornará ERROR_SUCCESS e armazenará o tamanho dos dados, em bytes, na variável apontada por pcbData. 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 pvData não for grande o suficiente para conter todos os dados retornados, a função retornará ERROR_MORE_DATA e o valor retornado por meio do parâmetro pcbData 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 RegGetValue novamente passando o tamanho do buffer atualizado no parâmetro pcbData . 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 pcbData é imprevisível.
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 pvData for muito pequeno para receber o valor, a função retornará ERROR_MORE_DATA.
Se o valor do registro lpValue não existir, a função retornará ERROR_FILE_NOT_FOUND.
Se dwFlags especificar uma combinação de RRF_SUBKEY_WOW6464KEY e RRF_SUBKEY_WOW6432KEY, a função retornará ERROR_INVALID_PARAMETER.
Comentários
Um aplicativo normalmente chama RegEnumValue para determinar os nomes de valor e, em seguida, RegGetValue para recuperar os dados dos nomes.
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 RegGetValueA 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 pvData.
Ao chamar essa função 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. 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.
Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0600 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
Observação
O cabeçalho winreg.h define RegGetValue 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 Vista, Windows XP Professional x64 Edition |
| Servidor mínimo com suporte | Windows Server 2008, Windows Server 2003 com SP1 |
| Plataforma de Destino | Windows |
| Cabeçalho | winreg.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |