Função RegEnumValueA (winreg.h)

Artigo
03/08/2023

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