RegEnumValueW 함수(winreg.h)

아티클
08/27/2023

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

구문

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

매개 변수

[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 문자를 포함하지 않고 버퍼에 저장된 문자 수를 받습니다.

레지스트리 값 이름은 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 반환합니다.

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 함수를 사용합니다.

예제

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

참고

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

요구 사항


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