Função RegEnumValueA (winreg.h)
Enumera os valores da chave do Registro aberta especificada. A função copia um nome de valor indexado e um bloco de dados para a chave sempre que ela é chamada.
Sintaxe
LSTATUS RegEnumValueA(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPSTR lpValueName,
[in, out] LPDWORD lpcchValueName,
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_USERS
[in] dwIndex
O índice do valor a ser recuperado. Esse parâmetro deve ser zero para a primeira chamada para a função RegEnumValue e, em seguida, ser incrementado para chamadas subsequentes.
Como os valores não são ordenados, qualquer novo valor terá um índice arbitrário. Isso significa que a função pode retornar valores em qualquer ordem.
[out] lpValueName
Um ponteiro para um buffer que recebe o nome do valor como uma cadeia de caracteres terminada em nulo.
Esse buffer deve ser grande o suficiente para incluir o caractere nulo de terminação.
Para obter mais informações, consulte Limites de tamanho do elemento do Registro.
[in, out] lpcchValueName
Um ponteiro para uma variável que especifica o tamanho do buffer apontado pelo parâmetro lpValueName , em caracteres. Quando a função retorna, a variável recebe o número de caracteres armazenados no buffer, não incluindo o caractere nulo de terminação.
Se o buffer especificado por lpValueName não for grande o suficiente para manter os dados, a função retornará ERROR_MORE_DATA e o tamanho do buffer na variável apontada por lpValueName não será alterado. Nesse caso, o conteúdo de lpcchValueName é indefinido.
Os nomes de valor do Registro são limitados a 32.767 bytes. A versão ANSI dessa função trata esse parâmetro como um valor SHORT . Portanto, se você especificar um valor maior que 32.767 bytes, haverá um estouro e a função poderá retornar ERROR_MORE_DATA.
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 da entrada de valor. Esse parâmetro poderá ser NULL se os dados não forem necessários.
Se lpData for NULL e lpcbData não for NULL, a função 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.
[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, a variável recebe o número de bytes armazenados no buffer.
Esse parâmetro 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. Para obter mais informações, consulte Comentários.
Se o buffer especificado por 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 de lpData é 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 não houver mais valores disponíveis, a função retornará ERROR_NO_MORE_ITEMS.
Se o buffer especificado por lpValueName ou lpData for muito pequeno para receber o valor, a função retornará ERROR_MORE_DATA.
Comentários
Para enumerar valores, um aplicativo deve chamar inicialmente a função RegEnumValue com o parâmetro dwIndex definido como zero. Em seguida, o aplicativo deve incrementar dwIndex e chamar a função RegEnumValue até que não haja mais valores (até que a função retorne ERROR_NO_MORE_ITEMS).
O aplicativo também pode definir dwIndex para o índice do último valor na primeira chamada para a função e decrementar o índice até que o valor com índice 0 seja enumerado. Para recuperar o índice do último valor, use a função RegQueryInfoKey .
Ao usar RegEnumValue, um aplicativo não deve chamar nenhuma função do Registro que possa alterar a chave que está sendo consultada.
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 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 de terminação nula.)
Para determinar o tamanho máximo do nome e dos buffers de dados, use a função RegQueryInfoKey .
Observação
Em versões herdadas do Windows, essa API também é exposta por kernel32.dll.
Exemplos
Para obter um exemplo, consulte Enumerando subchaves do Registro.
Observação
O cabeçalho winreg.h define RegEnumValue 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 |