NtQueryDirectoryFileEx 함수(ntifs.h)

아티클
03/10/2023

NtQueryDirectoryFileEx 루틴은 지정된 파일 핸들로 지정된 디렉터리의 파일에 대한 다양한 종류의 정보를 반환합니다.

구문

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

매개 변수

[in] FileHandle

정보가 요청되는 디렉터리를 나타내는 파일 개체에 대해 NtCreateFile 또는 NtOpenFile 에서 반환되는 핸들입니다. 호출자가 Event 또는 ApcRoutine에 대해 NULL이 아닌 값을 지정하는 경우 비동기 I/O에 대해 파일 개체를 열어야 합니다.

[in, optional] Event

호출자가 만든 이벤트에 대한 선택적 핸들입니다. 이 매개 변수가 제공되면 요청된 작업이 완료되고 지정된 이벤트가 Signaled 상태로 설정될 때까지 호출자가 대기 상태로 전환됩니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 호출자가 FileHandle 이 신호됨 상태로 설정될 때까지 대기하는 경우 NULL이어야 합니다.

[in, optional] ApcRoutine

요청된 작업이 완료될 때 호출할 선택적 호출자 제공 APC 루틴의 주소입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 파일 개체와 연결된 I/O 완료 개체가 있는 경우 이 매개 변수는 NULL이어야 합니다.

[in, optional] ApcContext

호출자가 APC를 제공하거나 I/O 완료 개체가 파일 개체와 연결된 경우 호출자가 결정한 컨텍스트 영역에 대한 선택적 포인터입니다. 작업이 완료되면 이 컨텍스트가 지정된 경우 APC에 전달되거나 I/O 관리자가 연결된 I/O 완료 개체에 게시하는 완료 메시지의 일부로 포함됩니다.

이 매개 변수는 선택 사항이며 NULL일 수 있습니다. ApcRoutine이 NULL이고 파일 개체와 연결된 I/O 완료 개체가 없는 경우 NULL이어야 합니다.

[out] IoStatusBlock

최종 완료 상태 및 작업에 대한 정보를 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터입니다. 데이터를 반환하는 성공적인 호출의 경우 FileInformation 버퍼에 기록된 바이트 수가 구조체의 정보 멤버에 반환됩니다.

[out] FileInformation

파일에 대한 원하는 정보를 수신하는 출력 버퍼에 대한 포인터입니다. 버퍼에 반환된 정보의 구조는 FileInformationClass 매개 변수에 의해 정의됩니다.

[in] Length

FileInformation이 가리키는 버퍼의 크기(바이트)입니다. 호출자는 지정된 FileInformationClass에 따라 이 매개 변수를 설정해야 합니다.

FileInformationClass

디렉터리의 파일에 대해 반환할 정보의 형식입니다. 디렉터리의 파일에 대해 반환할 정보 유형입니다. FileInformationClass 는 다음 FILE_INFORMATION_CLASS 값 중 하나일 수 있습니다.

값	의미
FileDirectoryInformation (1)	각 파일에 대한 FILE_DIRECTORY_INFORMATION 구조를 반환합니다.
FileFullDirectoryInformation (2)	각 파일에 대한 FILE_FULL_DIR_INFORMATION 구조를 반환합니다.
FileBothDirectoryInformation (3)	각 파일에 대한 FILE_BOTH_DIR_INFORMATION 구조를 반환합니다.
FileNamesInformation (12)	각 파일에 대한 FILE_NAMES_INFORMATION 구조를 반환합니다.
FileObjectIdInformation (29)	볼륨에 개체 ID가 있는 각 파일에 대한 FILE_OBJECTID_INFORMATION 구조를 반환합니다. 이 정보 클래스는 NTFS 볼륨의 특수 디렉터리 "\$Extend\$ObjId:$O:$INDEX_ALLOCATION"에만 유효합니다.
FileQuotaInformation (32)	할당량이 적용된 볼륨의 각 사용자에 대해 단일 FILE_QUOTA_INFORMATION 구조를 반환합니다. 이 정보 클래스는 NTFS 볼륨의 특수 디렉터리 "\$Extend\$Quota:$Q:$INDEX_ALLOCATION"에만 유효합니다.
FileReparsePointInformation (33)	볼륨에 재분석 지점이 있는 각 파일에 대해 단일 FILE_REPARSE_POINT_INFORMATION 구조를 반환합니다. 이 정보 클래스는 NTFS 및 ReFS 볼륨의 특수 디렉터리 "\$Extend\$Reparse:$R:$INDEX_ALLOCATION"에만 유효합니다.
FileIdBothDirectoryInformation (37)	각 파일에 대한 FILE_ID_BOTH_DIR_INFORMATION 구조를 반환합니다.
FileIdFullDirectoryInformation (38)	각 파일에 대한 FILE_ID_FULL_DIR_INFORMATION 구조를 반환합니다.
FileIdGlobalTxDirectoryInformation (50)	각 파일에 대한 FILE_ID_GLOBAL_TX_DIR_INFORMATION 구조를 반환합니다.
FileIdExtdDirectoryInformation (60)	각 파일에 대한 FILE_ID_EXTD_DIR_INFORMATION 구조를 반환합니다.
FileIdExtdBothDirectoryInformation (63)	각 파일에 대한 FILE_ID_EXTD_BOTH_DIR_INFORMATION 구조를 반환합니다.

[in] QueryFlags

SL_QUERY_DIRECTORY_MASK 포함된 플래그 중 하나 이상 가능한 값은 다음 표에 지정되어 있습니다.

값	의미
SL_RESTART_SCAN(0x00000001)	검사는 디렉터리의 첫 번째 항목에서 시작됩니다. 이 플래그를 설정하지 않으면 마지막 쿼리가 종료된 위치에서 검사가 다시 시작됩니다.
SL_RETURN_SINGLE_ENTRY(0x00000002)	일반적으로 반환 버퍼는 일치하는 디렉터리 항목으로 압축됩니다. 이 플래그가 설정되면 파일 시스템은 한 번에 하나의 디렉터리 항목만 반환합니다. 이렇게 하면 작업의 효율성이 떨어집니다.
SL_INDEX_SPECIFIED(0x00000004)	검사는 디렉터리의 지정된 인덱싱된 위치에서 시작해야 합니다. 이 플래그는 고유한 IRP_MJ_DIRECTORY_CONTROL IRP를 생성하는 경우에만 설정할 수 있습니다. 인덱스는 IRP에 지정됩니다. 위치를 지정하는 방법은 파일 시스템마다 다릅니다.
SL_RETURN_ON_DISK_ENTRIES_ONLY(0x00000008)	디렉터리 가상화 또는 Just-In-Time 확장을 수행하는 모든 파일 시스템 필터는 단순히 요청을 통해 파일 시스템으로 전달하고 현재 디스크에 있는 항목을 반환해야 합니다. 모든 파일 시스템에서 이 플래그를 지원하는 것은 아닙니다.
SL_NO_CURSOR_UPDATE_QUERY(0x00000010)	파일 시스템은 FileObject 디렉터리 커서 정보를 유지 관리합니다. 여러 스레드가 동일한 FileObject를 사용하여 쿼리를 수행하는 경우 FileObject별 구조체에 대한 액세스는 커서 상태의 손상을 방지하기 위해 단일 스레드가 됩니다. 이 플래그는 파일 시스템에 FileObject별 커서 상태 정보를 업데이트하지 않도록 지시하므로 여러 스레드가 동일한 핸들을 사용하여 병렬로 쿼리할 수 있습니다. 각 호출에서 SL_RESTART_SCAN 지정된 것처럼 동작합니다. 다음 호출에서 야생 카드 패턴이 지정되면 작업이 마지막 쿼리가 종료된 위치를 선택하지 않습니다. 이렇게 하면 진정한 비동기 디렉터리 쿼리를 지원할 수 있습니다. 이 플래그가 TxF 트랜잭션 내에서 사용되는 경우 작업이 실패합니다. 모든 파일 시스템에서 이 플래그를 지원하는 것은 아닙니다.

[in, optional] FileName

FileHandle에서 지정한 디렉터리 내에서 파일 이름(또는 와일드카드를 사용하는 경우 여러 파일)이 포함된 호출자가 할당한 유니코드 문자열에 대한 선택적 포인터입니다. 이 매개 변수는 선택 사항입니다.

FileName이 NULL이 아닌 경우 이름이 FileName 문자열과 일치하는 파일만 디렉터리 검사에 포함됩니다.
FileName이 NULL인 경우:
- SL_RETURN_SINGLE_ENTRY 쿼리 플래그에 설정되지 않은 경우 모든 파일이 포함됩니다.
- SL_RETURN_SINGLE_ENTRY 설정되면 하나의 파일만 포함됩니다.

FileName은 검색 식으로 사용되며 지정된 핸들에 대한 NtQueryDirectoryFileEx에 대한 첫 번째 호출에서 캡처됩니다. NtQueryDirectoryFileEx에 대한 후속 호출은 첫 번째 호출에서 검색 식 집합을 사용합니다. 후속 호출에 전달된 FileName 매개 변수는 무시됩니다.

반환 값

NtQueryDirectoryFileEx는 STATUS_SUCCESS 또는 적절한 오류 상태 반환합니다. 반환할 수 있는 오류 상태 값 집합은 파일 시스템별입니다. NtQueryDirectoryFileEx는 IoStatusBlock의 정보 멤버에서 지정된 FileInformation 버퍼에 실제로 기록된 바이트 수도 반환합니다. 몇 가지 가능한 오류 코드 및 이유는 다음과 같습니다.

반환 코드	의미
STATUS_BUFFER_OVERFLOW	출력 버퍼가 전체 파일 이름을 반환할 만큼 크지 않습니다.
STATUS_BUFFER_TOO_SMALL	출력 버퍼는 적어도 FileInformationClass로 식별된 기본 구조에 충분히 크지 않습니다.
STATUS_INVALID_INFO_CLASS	잘못된 FileInformationClass 가 지정되었거나 정보 클래스가 특수 조건에만 유효합니다(예: 특수 디렉터리에만 유효).
STATUS_INVALID_PARAMETER	매개 변수 중 하나가 파일 시스템에 유효하지 않습니다.

설명

NtQueryDirectoryFileEx 는 FileHandle이 나타내는 디렉터리에 포함된 파일에 대한 정보를 반환합니다.

제공된 경우 FileName은 지정된 FileHandle에 대한 NtQueryDirectoryFileEx에 대한 모든 후속 호출에 대한 디렉터리 검사에 포함된 항목을 결정합니다.

일치하는 항목이 하나 이상 있는 경우 NtQueryDirectoryFileEx 는 각 항목에 대해 FILE_XXX_INFORMATION 구조를 만들고 버퍼에 저장합니다.

일치하는 디렉터리 항목이 하나 이상 있다고 가정하면 정보가 반환되는 항목 수는 다음 중 가장 작 습니다.

QueryFlags에서 SL_RETURN_SINGLE_ENTRY 설정되고 FileName이 NULL인 경우 하나의 항목입니다.
FileName이 NULL이 아닌 경우 FileName 문자열과 일치하는 항목 수입니다. 문자열에 와일드카드가 없는 경우 일치하는 항목이 하나 이상 있을 수 있습니다.
정보가 지정된 버퍼에 맞는 항목의 수입니다.
디렉터리에 포함된 항목 수입니다.

NtQueryDirectoryFileEx에 대한 첫 번째 호출에서 찾은 첫 번째 항목에 대해 구조체가 너무 커서 출력 버퍼에 맞지 않는 경우 이 루틴은 다음을 수행합니다.

구조체의 고정 부분을 FileInformation의 출력 버퍼에 씁니다. 고정 부분은 최종 FileName 문자열을 제외한 모든 필드로 구성됩니다. 첫 번째 호출에서는 후속 호출이 아닌 I/O 시스템에서 버퍼가 적절한 FILE_XXX_INFORMATION 구조체의 고정 부분을 보유할 수 있을 만큼 충분히 큰지 확인합니다.
출력 버퍼에 적합한 만큼 FileName 문자열을 씁니다.
STATUS_BUFFER_OVERFLOW 같은 적절한 상태 값을 반환합니다.

각 호출에서 NtQueryDirectoryFileEx는 FileInformation이 가리키는 버퍼에 완전히 포함될 수 있는 만큼의 FILE_XXX_INFORMATION 구조체(디렉터리 항목당 하나)를 반환합니다.

첫 번째 호출에서 NtQueryDirectoryFileEx 는 출력 버퍼에 하나 이상의 전체 구조가 포함된 경우에만 STATUS_SUCCESS 반환합니다.
후속 호출에서 출력 버퍼에 구조체가 없는 경우 NtQueryDirectoryFileEx는 STATUS_SUCCESS 반환하지만 IoStatusBlock-Information> = 0을 설정하여 호출자에게 이 조건을 알립니다. 이 경우 호출자는 더 큰 버퍼를 할당하고 NtQueryDirectoryFileEx를 다시 호출해야 합니다. 나머지 항목에 대한 정보는 보고되지 않습니다. 따라서 위에 나열된 항목이 하나만 반환되는 경우를 제외하고 전체 디렉터리의 내용을 열거하려면 NtQueryDirectoryFileEx 를 두 번 이상 호출해야 합니다.

NtQueryDirectoryFileEx를 호출할 때 NtQueryDirectoryFileEx 호출과 병렬로 발생하는 디렉터리에 대한 변경 내용이 표시될 수 있습니다. 이 동작은 기본 파일 시스템의 구현에 따라 달라집니다.

NtQueryDirectoryFileEx에 대한 최종 호출은 빈 출력 버퍼를 반환하고 STATUS_NO_MORE_FILES 같은 적절한 상태 값을 보고합니다.

NtQueryDirectoryFileEx가 동일한 디렉터리에서 여러 번 호출되고 다른 작업에서 해당 디렉터리의 내용을 변경하는 경우 작업 타이밍에 따라 변경 내용이 표시되거나 표시되지 않을 수 있습니다.

NtQueryDirectoryFileEx 는 파일 시스템에서 지원되지 않는 FILE_XXX_INFORMATION 구조체의 모든 멤버에서 0을 반환합니다.

NtQueryDirectoryFileEx의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.

다른 파일 정보 쿼리 루틴에 대한 자세한 내용은 파일 개체를 참조하세요.

참고

커널 모드에서 NtQueryDirectoryFileEx 함수에 대한 호출이 발생하는 경우 "NtQueryDirectoryFileEx" 대신 "ZwQueryDirectoryFileEx"라는 이름을 사용해야 합니다.

커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 10, 버전 1709
머리글	ntifs.h
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL(설명 섹션 참조)