FltQueryDirectoryFile 함수(fltkernel.h)

아티클
08/07/2023

FltQueryDirectoryFile 루틴은 지정된 파일 개체로 지정된 디렉터리의 파일에 대한 다양한 종류의 정보를 반환합니다. 더 큰 쿼리 제어 를 위해 FltQueryDirectoryFileEx 를 사용합니다.

구문

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

매개 변수

[in] Instance

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

[in] FileObject

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

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

[in] ReturnSingleEntry

단일 항목만 반환해야 하는 경우 TRUE 로 설정하고, 그렇지 않으면 FALSE 로 설정합니다. 이 매개 변수가 TRUE이면 FltQueryDirectoryFile 은 발견된 첫 번째 항목만 반환합니다.

[in, optional] FileName

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

FileName이 NULL이 아닌 경우 이름이 FileName 문자열과 일치하는 파일만 디렉터리 검사에 포함됩니다. FileName이 NULL이면 모든 파일이 포함됩니다. RestartScan이 FALSE이면 FileName 값이 무시됩니다.

[in] RestartScan

디렉터리의 첫 번째 항목에서 검사를 시작하려면 TRUE 로 설정합니다. 이전 호출에서 검사를 다시 시작하면 FALSE 로 설정합니다. FltQueryDirectoryFile을 처음 호출할 때 호출자는 이 매개 변수를 TRUE로 설정해야 합니다.

[out, optional] LengthReturned

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

반환 값

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

설명

FltQueryDirectoryFile 은 FileObject로 표시되는 디렉터리에 포함된 파일에 대한 정보를 반환합니다.

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

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

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

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

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

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

참고

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

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

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

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista
대상 플랫폼	유니버설
헤더	fltkernel.h(Fltkernel.h 포함)
라이브러리	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL(설명 섹션 참조)