RegEnumKeyExA 함수(winreg.h)

아티클
03/11/2023

지정된 열린 레지스트리 키의 하위 키를 열거합니다. 함수는 호출할 때마다 하나의 하위 키에 대한 정보를 검색합니다.

구문

LSTATUS RegEnumKeyExA(
  [in]                HKEY      hKey,
  [in]                DWORD     dwIndex,
  [out]               LPSTR     lpName,
  [in, out]           LPDWORD   lpcchName,
                      LPDWORD   lpReserved,
  [in, out]           LPSTR     lpClass,
  [in, out, optional] LPDWORD   lpcchClass,
  [out, optional]     PFILETIME lpftLastWriteTime
);

매개 변수

[in] hKey

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

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

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] dwIndex

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

하위 키는 정렬되지 않으므로 새 하위 키에는 임의의 인덱스가 있습니다. 즉, 함수는 임의의 순서로 하위 키를 반환할 수 있습니다.

[out] lpName

종료 null 문자를 포함하여 하위 키의 이름을 수신하는 버퍼에 대한 포인터입니다. 함수는 전체 키 계층 구조가 아닌 하위 키의 이름만 버퍼에 복사합니다.

함수가 실패하면 이 버퍼에 정보가 복사되지 않습니다.

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

[in, out] lpcchName

lpName 매개 변수로 지정된 버퍼의 크기를 문자 단위로 지정하는 변수에 대한 포인터입니다. 이 크기에는 종료 null 문자가 포함되어야 합니다. 함수가 성공하면 lpcchName 이 가리키는 변수에는 종료 null 문자를 포함하지 않고 버퍼에 저장된 문자 수가 포함됩니다.

필요한 버퍼 크기를 확인하려면 RegQueryInfoKey 함수를 사용하여 hKey 매개 변수로 식별된 키에 대한 가장 큰 하위 키의 크기를 결정합니다.

lpReserved

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

[in, out] lpClass

열거형 하위 키의 사용자 정의 클래스를 수신하는 버퍼에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.

[in, out, optional] lpcchClass

lpClass 매개 변수로 지정된 버퍼의 크기를 문자 단위로 지정하는 변수에 대한 포인터입니다. 크기에는 종료 null 문자가 포함되어야 합니다. 함수가 성공하면 lpcchClass 에는 종료 null 문자를 포함하지 않고 버퍼에 저장된 문자 수가 포함됩니다. 이 매개 변수는 lpClass가 NULL인 경우에만 NULL일 수 있습니다.

[out, optional] lpftLastWriteTime

열거된 하위 키가 마지막으로 작성된 시간을 수신하는 FILETIME 구조체에 대한 포인터입니다. 이 매개 변수는 NULL일 수 있습니다.

반환 값

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

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

lpName 버퍼가 너무 작아서 키 이름을 수신하지 못하면 함수는 ERROR_MORE_DATA 반환합니다.

설명

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

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

애플리케이션이 RegEnumKeyEx 함수를 사용하는 동안 열거 중인 키를 변경할 수 있는 등록 함수를 호출해서는 안 됩니다.

특정 레지스트리 키에 액세스하는 작업은 리디렉션됩니다. 자세한 내용은 레지스트리의 레지스트리 가상화 및 32비트 및 64비트 애플리케이션 데이터를 참조하세요.

참고

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

예제

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

참고

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

요구 사항


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