IRegistryKey::EnumerateKey 메서드(portcls.h)

아티클
02/26/2024

메서드는 EnumerateKey 열린 키의 하위 키에 대한 정보를 반환합니다.

구문

NTSTATUS EnumerateKey(
  [in]  ULONG                 Index,
  [in]  KEY_INFORMATION_CLASS KeyInformationClass,
  [out] PVOID                 KeyInformation,
  [in]  ULONG                 Length,
  [out] PULONG                ResultLength
);

매개 변수

[in] Index

하위 키 인덱스를 지정합니다. 이 매개 변수는 키 정보가 요청되는 하위 키를 식별합니다. 키에 n 하위 키가 포함된 경우 유효한 인덱스는 0에서 n-1까지입니다. 인덱스가 이 범위를 초과하면 메서드는 STATUS_NO_MORE_ENTRIES 반환합니다.

[in] KeyInformationClass

버퍼에 반환할 정보의 형식을 지정합니다. 이 매개 변수를 다음 KEY_INFORMATION_CLASS 열거형 값 중 하나로 설정합니다.

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

[out] KeyInformation

키 정보 버퍼에 대한 포인터입니다. 이 매개 변수는 메서드가 요청된 데이터를 쓰는 호출자가 할당한 버퍼를 가리킵니다. 버퍼에는 KeyInformationClass 값에 따라 KEY_BASIC_INFORMATION, KEY_FULL_INFORMATION 또는 KEY_NODE_INFORMATION 형식의 구조가 포함됩니다. 구조체 뒤에는 키에 대해 요청되는 정보 유형에 따라 크기가 달라지는 유니코드 문자 문자열이 잇습니다.

[in] Length

호출자가 지정된 KeyInformationClass 에 따라 설정해야 하는 KeyInformation 버퍼의 크기(바이트)를 지정합니다. 호출이 성공하려면 버퍼는 메서드가 버퍼에 쓰는 데이터만큼 커야 합니다.

[out] ResultLength

결과 데이터의 길이에 대한 출력 포인터입니다. 이 매개 변수는 호출자가 할당한 ULONG 변수를 가리키며, 메서드는 실제로 KeyInformation 버퍼에 기록된 바이트 수를 지정하는 개수를 씁니다. 그러나 지정된 버퍼 길이가 너무 작아 정보를 포함할 수 없는 경우 메서드는 대신 필요한 버퍼 크기를 출력하고 STATUS_BUFFER_OVERFLOW 반환합니다.

반환 값

EnumerateKey 는 호출이 KeyInformation 버퍼에서 요청된 정보를 검색하는 데 성공하면 STATUS_SUCCESS 반환합니다. 지정한 버퍼 크기가 너무 작아서 사용 가능한 모든 정보를 수신하지 못하면 메서드는 STATUS_BUFFER_OVERFLOW 반환합니다. 그렇지 않으면 메서드는 적절한 오류 코드를 반환합니다. 다음 표에서는 가능한 반환 상태 코드 중 일부를 보여 줍니다.

반환 코드	설명
STATUS_BUFFER_TOO_SMALL	지정한 버퍼가 너무 작아서 정보를 받지 못했음을 나타냅니다.
STATUS_NO_MORE_ENTRIES	하위 키를 더 이상 사용할 수 없음을 나타냅니다(하위 키 인덱스가 하위 키 수보다 크거나 같음).