NtQueryDirectoryFile 함수(ntifs.h)
NtQueryDirectoryFile 루틴은 지정된 파일 핸들에 지정된 디렉터리의 파일에 대한 다양한 종류의 정보를 반환합니다.
통사론
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[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,
[in] FILE_INFORMATION_CLASS FileInformationClass,
[in] BOOLEAN ReturnSingleEntry,
[in, optional] PUNICODE_STRING FileName,
[in] BOOLEAN RestartScan
);
매개 변수
[in] FileHandle
정보가 요청되는 디렉터리를 나타내는 파일 개체에 대해 NtCreateFile 또는 NtOpenFile 반환된 핸들입니다. 호출자가 Event 대해 NULL이 아닌 값을 지정하거나 ApcRoutine 경우 파일 개체가 비동기 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 버퍼에 기록된 바이트 수가 구조체의 Information 멤버에 반환됩니다.
[out] FileInformation
파일에 대한 원하는 정보를 수신하는 버퍼에 대한 포인터입니다. 버퍼에 반환된 정보의 구조는 FileInformationClass 매개 변수에 의해 정의됩니다.
[in] Length
fileInformation 가리키는 버퍼의 크기(바이트)입니다. 호출자는 지정된 FileInformationClass따라 이 매개 변수를 설정해야 합니다.
[in] FileInformationClass
디렉터리의 파일에 대해 반환할 정보의 형식입니다. 디렉터리의 파일에 대해 반환할 정보 유형입니다. 가능한 값 목록은 NtQueryDirectoryFileExFileInformationClass 매개 변수를 참조하세요.
[in] ReturnSingleEntry
단일 항목만 반환해야 하는 경우 TRUE 설정되고, 그렇지 않으면 FALSE . 이 매개 변수가 TRUE 경우 NtQueryDirectoryFile 첫 번째 항목만 반환합니다.
[in, optional] FileName
fileHandle 지정된 디렉터리 내에서 파일 이름(또는 와일드카드를 사용하는 경우 여러 파일)이 포함된 호출자 할당 유니코드 문자열에대한 선택적 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.
FileName NULL이 아니면 이름이 FileName 문자열과 일치하는 파일만 디렉터리 검사에 포함됩니다. FileName NULL이면 모든 파일이 포함됩니다.
FileName 검색 식으로 사용되며 지정된 핸들에 대한 NtQueryDirectoryFile 첫 번째 호출에서 캡처됩니다. NtQueryDirectoryFile 대한 후속 호출은 첫 번째 호출에서 설정된 검색 식을 사용합니다. 후속 호출에 전달된 FileName 매개 변수는 무시됩니다.
[in] RestartScan
디렉터리의 첫 번째 항목에서 검사를 시작하는 경우 TRUE 설정합니다. 이전 호출에서 검사를 다시 시작하면 false 설정합니다.
특정 핸들에 대해 NtQueryDirectoryFile 루틴이 호출되면 RestartScan 매개 변수는 값에 관계없이 TRUE 설정된 것처럼 처리됩니다. 후속 NtQueryDirectoryFile 호출에서 RestartScan 매개 변수의 값이 적용됩니다.
반환 값
NtQueryDirectoryFile루틴은 STATUS_SUCCESS 또는 적절한 오류 상태를 반환합니다. 반환할 수 있는 오류 상태 값 집합은 파일 시스템별 값입니다. NtQueryDirectoryFileIoStatusblockInformation 멤버에서 지정된 FileInformation 버퍼에 실제로 기록된 바이트 수도 반환합니다. 몇 가지 가능한 오류 코드 목록은 NtQueryDirectoryFileEx 참조하세요.
발언
NtQueryDirectoryFile 루틴은 FileHandle표시되는 디렉터리에 포함된 파일에 대한 정보를 반환합니다.
제공된 경우 FileName 매개 변수 값은 지정된 FileHandle대한 NtQueryDirectoryFile 대한 모든 후속 호출에 대한 디렉터리 검사에 포함된 항목을 결정합니다.
일치하는 항목이 하나 이상 있는 경우 NtQueryDirectoryFile 각 항목에 대한 FILE_XXX_INFORMATION 구조를 만들고 버퍼에 저장합니다.
일치하는 디렉터리 항목이 하나 이상 있다고 가정하면 정보가 반환되는 항목 수는 다음 중 *가장 작은.
- 한 항목은 ReturnSingleEntry TRUE FileName 경우 NULL입니다.
- FileName NULL이 아닌 경우 FileName 문자열과 일치하는 항목 수입니다. (문자열에 와일드카드가 없는 경우 일치하는 항목이 하나 이상 있을 수 있습니다.)
- 해당 정보가 지정된 버퍼에 맞는 항목 수입니다.
- 디렉터리에 포함된 항목 수입니다.
NtQueryDirectoryFile 첫 번째 호출에서 발견된 첫 번째 항목에 대해 생성된 구조체가 너무 커서 출력 버퍼에 맞지 않는 경우 루틴은 구조체의 고정 부분을 출력 버퍼에 씁니다. 그런 다음 루틴은 FileName 문자열의 많은 부분을 출력 버퍼에 씁니다. 구조체의 고정 부분은 최종 FileName 문자열을 제외한 모든 필드로 구성됩니다. 첫 번째 호출에서 후속 호출이 아닌 I/O 시스템은 버퍼가 적절한 FILE_XXX_INFORMATION 구조체의 고정 부분을 보유할 수 있을 만큼 충분히 큰지 확인합니다.) 이 경우 NtQueryDirectoryFile STATUS_BUFFER_OVERFLOW 같은 적절한 상태 값을 반환합니다.
각 호출에서 NtQueryDirectoryFileFileInformation가리키는 버퍼에 완전히 포함될 수 있는 만큼의 FILE_XXX_INFORMATION 구조(디렉터리 항목당 하나)를 반환합니다. 첫 번째 호출에서 NtQueryDirectoryFile 출력 버퍼에 하나 이상의 전체 구조가 포함된 경우에만 STATUS_SUCCESS 반환합니다. 후속 호출에서 출력 버퍼에 구조가 없는 경우 NtQueryDirectoryFile STATUS_SUCCESS 반환하지만 IoStatusblock설정합니다.>Information = 0을 설정하여 호출자에게 이 조건을 알립니다. 이 경우 호출자는 더 큰 버퍼를 할당하고 NtQueryDirectoryFile 다시 호출해야 합니다. 나머지 항목에 대한 정보는 보고되지 않습니다. 따라서 위에 나열된 항목이 하나만 반환되는 경우를 제외하고 전체 디렉터리의 내용을 열거하려면 NtQueryDirectoryFile 두 번 이상 호출해야 합니다.
NtQueryDirectoryFile호출할 때 NtQueryDirectoryFile 호출과 동시에 발생하는 디렉터리에 대한 변경 내용을 볼 수 있습니다. 이 동작은 기본 파일 시스템의 구현에 따라 달라집니다.
NtQueryDirectoryFile 대한 마지막 호출은 빈 출력 버퍼를 반환하고 STATUS_NO_MORE_FILES 같은 적절한 상태 값을 보고합니다.
NtQueryDirectoryFile 동일한 디렉터리에서 여러 번 호출되고 다른 작업에서 해당 디렉터리의 내용을 변경하는 경우 작업 타이밍에 따라 변경 내용이 표시되거나 표시되지 않을 수 있습니다.
NtQueryDirectoryFile파일 시스템에서 지원되지 않는 FILE_XXX_INFORMATION 구조체의 멤버에서 0을 반환합니다.
NtQueryDirectoryFile 호출자는 사용하도록 설정된 특수 커널 APC를 사용하여 IRQL = PASSIVE_LEVEL 및실행되어야 합니다.
다른 파일 정보 쿼리 루틴에 대한 자세한 내용은 파일 개체 참조하세요.
메모
NtQueryDirectoryFile 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwQueryDirectoryFile" 대신 "NtQueryDirectoryFile" 이름을 사용해야 합니다.
커널 모드 드라이버의 호출의 경우 NtXXX 및 ZwXXX 버전의 Windows Native System Services 루틴은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. NtXXX 및 ZwXXX 루틴 버전 간의 관계에 대한 자세한 내용은 네이티브 System Services 루틴 Nt 및 Zw 버전 사용참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP |
| 대상 플랫폼 | 보편적 |
| 헤더 | ntifs.h(Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL(설명 섹션 참조) |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs, PowerIrpDDis |