Função RegEnumValueW (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 RegEnumValueW(
[in] HKEY hKey,
[in] DWORD dwIndex,
[out] LPWSTR 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 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_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 um cadeia de caracteresterminada em nulo.
Esse buffer deve ser grande o suficiente para incluir a terminação caractere de nulo.
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 a terminação caractere de nulo.
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 forNULL, 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 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 de. 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 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 não houver mais valores disponíveis, a função retornará ERROR_NO_MORE_ITEMS.
Se o buffer lpData
Observações
Para enumerar valores, um aplicativo deve inicialmente chamar 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 o í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, talvez a cadeia de caracteres não tenha sido armazenada com os caracteres nulosnulos
Para determinar o tamanho máximo do nome e dos buffers de dados, use a função
Exemplos
Para obter um exemplo, consulte Enumerando subchaves do Registro.
Nota
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 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