RegEnumValueA 함수(winreg.h)

아티클
03/08/2023

지정된 열린 레지스트리 키의 값을 열거합니다. 함수는 호출될 때마다 키에 대해 하나의 인덱싱된 값 이름과 데이터 블록을 복사합니다.

구문

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

매개 변수

[in] hKey

열린 레지스트리 키에 대한 핸들입니다. 키는 KEY_QUERY_VALUE 액세스 권한으로 열려 있어야 합니다. 자세한 내용은 레지스트리 키 보안 및 액세스 권한을 참조하세요.

이 핸들은 RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx 또는 RegOpenKeyTransacted 함수에서 반환됩니다. 다음 미리 정의된 키 중 하나일 수도 있습니다.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

검색할 값의 인덱스입니다. 이 매개 변수는 RegEnumValue 함수에 대한 첫 번째 호출에 대해 0이어야 하며 이후 호출에 대해 증가해야 합니다.

값은 순서가 지정되지 않으므로 새 값에는 임의의 인덱스가 있습니다. 즉, 함수는 임의의 순서로 값을 반환할 수 있습니다.

[out] lpValueName

값의 이름을 null로 끝나는 문자열로 수신하는 버퍼에 대한 포인터입니다.

이 버퍼는 종료 null 문자를 포함할 만큼 커야 합니다.

자세한 내용은 레지스트리 요소 크기 제한을 참조하세요.

[in, out] lpcchValueName

lpValueName 매개 변수가 가리키는 버퍼의 크기를 문자 단위로 지정하는 변수에 대한 포인터입니다. 함수가 반환되면 변수는 종료 null 문자를 포함하지 않고 버퍼에 저장된 문자 수를 받습니다.

lpValueName으로 지정된 버퍼가 데이터를 저장할 만큼 크지 않으면 함수는 ERROR_MORE_DATA 반환하고 lpValueName이 가리키는 변수의 버퍼 크기는 변경되지 않습니다. 이 경우 lpcchValueName 의 내용은 정의되지 않습니다.

레지스트리 값 이름은 32,767바이트로 제한됩니다. 이 함수의 ANSI 버전은 이 매개 변수를 SHORT 값으로 처리합니다. 따라서 32,767바이트보다 큰 값을 지정하면 오버플로가 있고 함수가 ERROR_MORE_DATA 반환할 수 있습니다.

lpReserved

이 매개 변수는 예약되어 있으며 NULL이어야 합니다.

[out, optional] lpType

지정된 값에 저장된 데이터 형식을 나타내는 코드를 수신하는 변수에 대한 포인터입니다. 가능한 형식 코드 목록은 레지스트리 값 형식을 참조하세요. 형식 코드가 필요하지 않은 경우 lpType 매개 변수는 NULL 일 수 있습니다.

[out, optional] lpData

값 항목에 대한 데이터를 수신하는 버퍼에 대한 포인터입니다. 데이터가 필요하지 않은 경우 이 매개 변수는 NULL 일 수 있습니다.

lpData가 NULL이고 lpcbData가 NULL이 아닌 경우 함수는 lpcbData가 가리키는 변수에 데이터 크기를 바이트 단위로 저장합니다. 이렇게 하면 애플리케이션이 데이터에 대한 버퍼를 할당하는 가장 좋은 방법을 결정할 수 있습니다.

[in, out, optional] lpcbData

lpData 매개 변수가 가리키는 버퍼의 크기를 바이트 단위로 지정하는 변수에 대한 포인터입니다. 함수가 반환되면 변수는 버퍼에 저장된 바이트 수를 받습니다.

lpData가 NULL인 경우에만 이 매개 변수는 NULL일 수 있습니다.

데이터에 REG_SZ, REG_MULTI_SZ 또는 REG_EXPAND_SZ 형식이 있는 경우 이 크기에는 종료 되는 null 문자 또는 문자가 포함됩니다. 자세한 내용은 설명 부분을 참조하세요.

lpData로 지정된 버퍼가 데이터를 저장할 만큼 크지 않으면 함수는 ERROR_MORE_DATA 반환하고 lpcbData가 가리키는 변수에 필요한 버퍼 크기를 저장합니다. 이 경우 lpData 의 내용은 정의되지 않습니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드입니다. 사용할 수 있는 값이 더 이상 없으면 함수는 ERROR_NO_MORE_ITEMS 반환합니다.

lpValueName 또는 lpData로 지정된 버퍼가 너무 작아서 값을 받지 못하면 함수는 ERROR_MORE_DATA 반환합니다.

설명

값을 열거하려면 애플리케이션이 처음에 dwIndex 매개 변수를 0으로 설정하여 RegEnumValue 함수를 호출해야 합니다. 그런 다음, 애플리케이션은 dwIndex 를 증가시키고 더 이상 값이 없을 때까지 RegEnumValue 함수를 호출해야 합니다(함수가 ERROR_NO_MORE_ITEMS 반환될 때까지).

또한 애플리케이션은 함수에 대한 첫 번째 호출에서 마지막 값의 인덱스로 dwIndex 를 설정하고 인덱스 0이 있는 값이 열거될 때까지 인덱스를 감소할 수 있습니다. 마지막 값의 인덱스 검색하려면 RegQueryInfoKey 함수를 사용합니다.

RegEnumValue를 사용하는 동안 애플리케이션은 쿼리 중인 키를 변경할 수 있는 레지스트리 함수를 호출해서는 안 됩니다.

데이터에 REG_SZ, REG_MULTI_SZ 또는 REG_EXPAND_SZ 형식이 있는 경우 문자열이 적절한 null 종료 문자와 함께 저장되지 않았을 수 있습니다. 따라서 함수가 ERROR_SUCCESS 반환하더라도 애플리케이션은 문자열을 사용하기 전에 문자열이 제대로 종료되었는지 확인해야 합니다. 그렇지 않으면 버퍼를 덮어쓸 수 있습니다. (REG_MULTI_SZ 문자열에는 두 개의 null로 끝나는 문자가 있어야 합니다.

이름 및 데이터 버퍼의 최대 크기를 확인하려면 RegQueryInfoKey 함수를 사용합니다.

참고

레거시 버전의 Windows에서도 이 API는 kernel32.dll 의해 노출됩니다.

예제

예제는 레지스트리 하위 키 열거를 참조하세요.

참고

winreg.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 RegEnumValue를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	winreg.h(Windows.h 포함)
라이브러리	Advapi32.lib
DLL	Advapi32.dll