FltQueryDirectoryFileEx 함수(fltkernel.h)

아티클
02/29/2024

FltQueryDirectoryFileEx 는 지정된 파일 개체로 지정된 디렉터리의 파일에 대한 다양한 종류의 정보를 반환합니다.

구문

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

매개 변수

Instance

이 I/O를 시작하는 미니필터 드라이버 instance 대한 불투명 포인터입니다.

FileObject

쿼리할 디렉터리를 나타내는 파일 개체에 대한 포인터입니다.

FileInformation

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

Length

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

FileInformationClass

디렉터리의 파일에 대해 반환할 정보 유형입니다. 가능한 값 목록은 NtQueryDirectoryFileEx의 FileInformationClass 매개 변수를 참조하세요.

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 트랜잭션 내에서 사용되는 경우 작업이 실패합니다. 모든 파일 시스템에서 이 플래그를 지원하는 것은 아닙니다.

FileName

FileObject에서 지정한 디렉터리 내에서 파일 이름(또는 와일드카드를 사용하는 경우 여러 파일)이 포함된 유니코드 문자열이 있는 호출자가 할당한 UNICODE_STRING 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. fileName이 NULL이면 모든 파일이 포함됩니다.

FileName이 NULL이 아닌 경우 이름이 FileName 문자열과 일치하는 파일만 디렉터리 검사에 포함됩니다. QueryFlagsResetScan 플래그가 설정되면 FileName 값이 무시됩니다.

LengthReturned

지정된 FileInformation 버퍼에 실제로 기록된 바이트 수를 받습니다.

반환 값

FltQueryDirectoryFileEx 는 STATUS_SUCCESS 또는 적절한 오류 코드를 반환합니다. 반환할 수 있는 오류 상태 값 집합은 파일 시스템별입니다.

설명

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

FltQueryDirectoryFileEx에 대한 첫 번째 호출은 QueryFlags 및 FileName 값을 기반으로 모든 후속 호출에 대한 디렉터리 검사에 포함할 항목 집합을 결정합니다. 일치하는 항목이 하나 이상 있는 경우 FltQueryDirectoryFileEx 는 각 항목에 대해 FILE_XXX_INFORMATION 구조체(위 표 참조)를 만들고 버퍼에 구조를 저장합니다.

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

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

FltQueryDirectoryFileEx에 대한 첫 번째 호출에서 첫 번째 찾은 항목에 대해 생성된 구조체가 출력 버퍼에 맞지 않는 경우 구조체의 고정 부분만 반환됩니다. 고정 부분은 최종 FileName 문자열을 제외한 구조체의 모든 필드로 구성됩니다. I/O 하위 시스템은 버퍼가 적절한 FILE_XXX_INFORMATION 구조체의 고정 부분을 보유할 수 있을 만큼 충분히 큰지 확인합니다(후속 호출이 아닌 첫 번째 호출에만 해당). 이 경우 FltQueryDirectoryFileEx는 STATUS_BUFFER_OVERFLOW 상태 값을 반환합니다. 또한 FltQueryDirectoryFileEx에 대한 첫 번째 호출에서 FileName 매개 변수와 일치하는 FileObject 디렉터리에 파일이 없으면 FltQueryDirectoryFileEx는 STATUS_NO_SUCH_FILE 반환합니다.

각 호출에서 FltQueryDirectoryFileEx는 FileInformation이 가리키는 버퍼에 완전히 포함될 수 있는 만큼의 FILE_XXX_INFORMATION 구조체(디렉터리 항목당 하나)를 반환합니다. 출력 버퍼에 하나 이상의 전체 구조체가 포함되어 있는 한 반환되는 상태 값은 STATUS_SUCCESS. 나머지 항목에 대한 정보는 보고되지 않습니다. 따라서 위에 나열된 항목이 하나만 반환되는 경우를 제외하고 전체 디렉터리의 내용을 열거하려면 FltQueryDirectoryFileEx 를 두 번 이상 호출해야 합니다(예: FileName 매개 변수에 와일드카드 문자가 하나 이상 있거나 NULL인 경우).

FltQueryDirectoryFileEx에 대한 마지막 호출은 빈 출력 버퍼를 반환하고 오류 없는 상태 값인 STATUS_NO_MORE_FILES 보고합니다.

참고:FltQueryDirectoryFileEx 가 동일한 디렉터리에서 여러 번 호출되는 경우 정보가 반환되는 항목 수가 예상보다 적을 수 있습니다. 디렉터리 검사에 포함할 항목 집합이 FltQueryDirectoryFileEx에 대한 첫 번째 호출에서 수정되었기 때문입니다. 후속 호출에서 FltQueryDirectoryFileEx 는 이 동일한 열거형에서 중단된 디렉터리 검사를 다시 시작합니다. 그러나 FltQueryDirectoryFileEx 호출 사이에 실제 디렉터리 항목이 더 이상 원래 열거형과 동기화되지 않도록 변경할 수 있습니다.

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

FltQueryDirectoryFileEx의 호출자는 IRQL = PASSIVE_LEVEL 및 APC를 사용하도록 설정된 상태에서 실행되어야 합니다. 자세한 내용은 APC 사용 안 을 참조하세요.