RegEnumValueW 함수(winreg.h)

아티클
11/20/2024

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

통사론

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-terminated 문자열로 값의 이름을 수신하는 버퍼에 대한 포인터입니다.

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

자세한 내용은 Registry 요소 크기 제한참조하세요.

[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 증가시키고 값이 더 이상 없을 때까지(함수가 ERROR_NO_MORE_ITEMS 반환될 때까지) RegEnumValue 함수를 호출해야 합니다.

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

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

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

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

예제

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

메모

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

요구 사항

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