FltGetFileNameInformation 함수(fltkernel.h)

아티클
08/07/2023

FltGetFileNameInformation 루틴은 파일 또는 디렉터리에 대한 이름 정보를 반환합니다.

구문

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

매개 변수

[in] CallbackData

I/O 작업에 대한 콜백 데이터 구조인 FLT_CALLBACK_DATA 구조체에 대한 포인터입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[in] NameOptions

반환할 이름 정보의 형식과 필터 관리자가 사용할 쿼리 메서드를 지정하는 플래그가 포함된 FLT_FILE_NAME_OPTIONS 값입니다. 호출자는 이름 형식 플래그와 쿼리 메서드 플래그를 포함해야 합니다. 이름 공급자 미니필터 드라이버에서 추가 플래그를 사용하여 이름 쿼리 옵션을 지정할 수 있습니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

다음은 파일 이름 형식 플래그 값입니다. 다음 플래그 중 하나만 지정할 수 있습니다. 이러한 형식에 대한 설명은 FLT_FILE_NAME_INFORMATION.

이름 형식 플래그 값	의미
FLT_FILE_NAME_NORMALIZED	FileNameInformation 매개 변수는 파일의 정규화된 이름을 포함하는 구조체의 주소를 받습니다.
FLT_FILE_NAME_OPENED	FileNameInformation 매개 변수는 파일을 열 때 사용된 이름을 포함하는 구조체의 주소를 받습니다.
FLT_FILE_NAME_SHORT	FileNameInformation 매개 변수는 파일의 짧은 이름(8.3)을 포함하는 구조체의 주소를 받습니다. 짧은 이름은 최대 8자로 구성되며 마침표 바로 뒤에 최대 3자까지 추가됩니다. 파일의 짧은 이름에는 볼륨 이름, 디렉터리 경로 또는 스트림 이름이 포함되지 않습니다. 사전 만들기 경로에서 유효하지 않습니다.

다음은 파일 이름 쿼리 메서드 플래그 값입니다. 다음 플래그 중 하나만 지정할 수 있습니다.

Query 메서드 플래그 값	의미
FLT_FILE_NAME_QUERY_DEFAULT	파일 이름을 쿼리하는 것이 현재 안전하지 않은 경우 FltGetFileNameInformation 은 아무 것도 수행하지 않습니다. 그렇지 않으면 FltGetFileNameInformation 에서 파일 이름 정보에 대한 필터 관리자의 이름 캐시를 쿼리합니다. 캐시에 이름이 없으면 FltGetFileNameInformation 은 파일 시스템을 쿼리하고 결과를 캐시합니다.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation 은 파일 이름 정보에 대해 필터 관리자의 이름 캐시를 쿼리합니다. FltGetFileNameInformation 은 파일 시스템을 쿼리하지 않습니다.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation 은 파일 시스템에 파일 이름 정보를 쿼리합니다. FltGetFileNameInformation 은 필터 관리자의 이름 캐시를 쿼리하지 않으며 파일 시스템 쿼리의 결과를 캐시하지 않습니다.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformation 은 파일 이름 정보에 대해 필터 관리자의 이름 캐시를 쿼리합니다. 캐시에서 이름을 찾을 수 없으며 현재 안전한 경우 FltGetFileNameInformation 은 파일 시스템에 파일 이름 정보를 쿼리하고 결과를 캐시합니다.

이름 공급자 미니필터는 다음 플래그를 사용하여 파일 이름 작업의 속성을 지정합니다.

이름 공급자 플래그 값	의미
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	이름 공급자 미니필터는 이 플래그를 사용하여 이름 쿼리 요청이 스택의 하위 이름 공급자에 의해 충족되지 않고 자체(이름 공급자 미니필터)로 리디렉션되도록 지정할 수 있습니다.
FLT_FILE_NAME_DO_NOT_CACHE	이 플래그는 이 쿼리에서 검색된 이름을 캐시해서는 안 됨을 표시합니다. 이름 공급자 미니필터는 중간 쿼리를 수행하여 이름을 생성할 때 이 플래그를 사용합니다.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	이름 공급자 미니필터는 이 플래그를 사용하여 STATUS_REPARSE 반환된 경우에도 사후 만들기 경로에서 이름을 쿼리하는 것이 안전하도록 지정할 수 있습니다. FileObject-FileName> 필드가 변경되지 않았는지 확인하는 것은 호출자의 책임입니다. 탑재 지점 또는 기호 링크 재분석 지점과 함께 이 플래그를 사용하지 마세요.

[out] FileNameInformation

파일 이름 정보를 포함하는 시스템 할당 FLT_FILE_NAME_INFORMATION 구조체의 주소를 수신하는 호출자가 할당한 변수에 대한 포인터입니다. FltGetFileNameInformation 은 페이징된 풀에서 이 구조를 할당합니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

반환 값

이름 정보가 성공적으로 반환되면 FltGetFileNameInformation 은 STATUS_SUCCESS 반환합니다. 그렇지 않으면 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.

반환 코드	설명
STATUS_FLT_INVALID_NAME_REQUEST	필터 관리자의 이름 캐시에서 쿼리를 충족할 수 없는 경우 FltGetFileNameInformation은 다음 상황에서 파일 이름 정보를 가져올 수 없습니다. 페이징 I/O 경로에 있습니다. 현재 스레드의 TopLevelIrp 필드가 NULL이 아닌 경우 결과 파일 시스템 재귀로 인해 교착 상태 또는 스택 오버플로가 발생할 수 있기 때문입니다. (이 문제에 대한 자세한 내용은 IoGetTopLevelIrp를 참조하세요.) IRP_MJ_CLEANUP 작업이 완료된 후 즉, 클린 이후, 사전 닫기 또는 사후 닫기 경로(대상 파일 개체에는 FO_CLEANUP_COMPLETE 플래그 집합이 있음)입니다. 다음 작업에 대한 사전 작업(PFLT_PRE_OPERATION_CALLBACK) 또는 PFLT_POST_OPERATION_CALLBACK(사후 작업) 콜백 루틴에서: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION 대한 사후 콜백 루틴입니다. 모든 APC를 사용하지 않도록 설정한 경우 즉, KeAreAllApcsDisabled 가 TRUE를 반환하는 경우입니다. FltGetFileNameInformation 은 사전 만들기 경로에서 파일의 짧은 이름을 가져올 수 없습니다. STATUS_FLT_INVALID_NAME_REQUEST 오류 코드입니다.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation 에서 풀 할당 오류가 발생했습니다. 오류 코드입니다.
STATUS_INVALID_PARAMETER	다음 중 하나와 같이 잘못된 매개 변수가 전달될 때 반환됩니다. FileNameInformation 매개 변수는 NULL일 수 없습니다. CallbackData 매개 변수는 NULL일 수 없습니다. STATUS_INVALID_PARAMETER 오류 코드입니다.
STATUS_FLT_NAME_CACHE_MISS	파일 이름 정보는 이름 캐시에서 찾을 수 없으며 NameOptions 에는 FLT_FILE_NAME_QUERY_CACHE_ONLY 포함됩니다. 또는 NameOptions에 FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP 포함되고 파일 시스템에서 파일 이름 정보를 쿼리할 수 없는 경우 이름 캐시에서 파일 이름 정보를 찾을 수 없습니다. NameOptions에서 FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY 설정된 FltGetFileNameInformation에 대한 추가 호출은 파일 이름 정보를 반환할 수 있습니다.
STATUS_NOT_SAME_DEVICE	미리 만드는 동안 쿼리되는 파일은 부모 디렉터리가 아닌 다른 볼륨에 있습니다. 이 오류는 파일이 다른 볼륨으로 확인된 접합 또는 symlink인 정규화된 이름 쿼리에 대해 반환됩니다.
STATUS_ACCESS_DENIED	사용자가 파일 ID로 파일을 열었지만 전체 경로에 대한 트래버스 권한이 없으면 FltGetFileNameInformation 이 이 반환 값으로 실패합니다. STATUS_ACCESS_DENIED 오류 코드입니다. 또는 파일은 모든 액세스가 거부된 시스템 파일입니다.

설명

FltGetFileNameInformation 은 CallbackData에서 설명한 작업의 대상인 파일 또는 디렉터리에 대해 요청된 이름 정보를 지정된 형식으로 반환합니다. 파일 또는 디렉터리를 파일 시스템에서 아직 열 필요가 없습니다.

사전 만들기 작업의 경우 CallbackData-Iopb-OperationFlags>> 멤버에 SL_OPEN_TARGET_DIRECTORY 비트 플래그가 포함된 경우 FltGetFileNameInformation은 지정된 파일에 대한 포함(부모) 디렉터리의 이름을 반환합니다. 이 이름은 만들기 작업이 열리는 실제 경로입니다.

FltGetFileNameInformation에서 반환된 FLT_FILE_NAME_INFORMATION 구조체의 내용을 구문 분석하려면 FltParseFileNameInformation을 호출합니다. 파일 이름 형식에 대한 자세한 내용은 FLT_FILE_NAME_INFORMATION 참조하세요.

FltGetFileNameInformation을 성공적으로 호출한 후 호출자는 포인터가 더 이상 필요하지 않을 때 FileNameInformation 매개 변수에 반환된 포인터를 해제합니다. 호출자는 FltReleaseFileNameInformation을 호출하여 이 작업을 수행합니다.

이 구조는 모든 미니필터 드라이버에서 사용할 수 있도록 필터 관리자에 의해 캐시되므로 호출자는 FileNameInformation 매개 변수에 반환된 구조체의 내용을 수정해서는 안 됩니다.

열린 이름을 검색하기 위한 만들기 작업의 사전 운용 콜백 루틴에서 FltGetFileNameInformation 이 호출되면 열려 있는 파일의 경로가 볼륨에 없더라도 FltGetFileNameInformation 이 성공합니다.

정규화된 이름을 검색하기 위한 만들기 작업에 대한 사전 운용 콜백 루틴에서 FltGetFileNameInformation 이 호출되면 열려 있는 파일 경로의 최종 구성 요소가 볼륨에 없더라도 FltGetFileNameInformation 이 성공합니다.

참고

원격 볼륨에서 정규화된 파일 이름을 쿼리하기 위한 SMB(서버 메시지 블록) 지원은 다른 Windows 10 버전에 따라 다릅니다. 자세한 내용은 MS-SMB2 프로토콜 을 참조하세요.

만들기, 하드 링크 및 이름 바꾸기 작업에서 파일 이름 터널링으로 인해 미니필터 드라이버가 사전 작업 콜백 루틴에서 검색하는 정규화된 파일 이름 정보의 최종 구성 요소가 무효화될 수 있습니다. 미니필터 드라이버가 FltGetFileNameInformation과 같은 루틴을 호출하여 사전 운용 콜백(PFLT_PRE_OPERATION_CALLBACK) 루틴에서 정규화된 파일 이름 정보를 검색하는 경우 파일에 대한 올바른 파일 이름 정보를 검색하려면 PFLT_POST_OPERATION_CALLBACK(Postoperation 콜백) 루틴에서 FltGetTunneledName을 호출해야 합니다.

Windows 8.1 이전 버전의 경우 FltGetFileNameInformation은 필터의 미리 만들기 콜백에서 호출된 경우에만스트림 형식을 포함할 수 있습니다. 파일의 기본 스트림과 메타데이터 스트림을 구분하려면 미리 만들기 작업에서 이 호출을 수행해야 합니다. 결과 스트림 형식은 파일의 수명 동안 유효한 상태로 유지됩니다.

Windows 8 전에 Filter Manager는 파일 경로의 각 구성 요소에 대한 이름 정보를 수집하여 파일 또는 디렉터리의 정규화된 이름을 얻었습니다. 이렇게 하려면 전체 경로를 컴파일하기 위해 파일 시스템에 대한 여러 쿼리가 필요했습니다. Windows 8 부터 로컬 파일 시스템은 FileNormalizedNameInformation 파일 정보 클래스를 지원하며 정규화된 이름을 얻으려면 단일 쿼리만 필요합니다. 원격 파일 시스템은 FileNormalizedNameInformation 파일 정보 클래스를 지원하지 않을 수 있습니다. 이 경우 정규화된 이름을 어셈블하려면 파일 경로의 각 구성 요소에 대한 쿼리가 여전히 필요합니다. 특정 네트워크 조건에서 전체 이름 쿼리를 완료하는 데 상당한 시간이 필요할 수 있습니다.

정규화된 파일 이름 정보에 대한 자세한 내용은 FLT_FILE_NAME_INFORMATION 참조하세요.

참고

파일 이름 터널링에서는 이러한 방식으로 만들기, 하드 링크 및 이름 바꾸기 작업에만 영향을 줍니다. 읽기 및 쓰기와 같은 다른 I/O 작업에는 영향을 주지 않습니다.

다음 쌍을 이루는 작업으로 인해 파일 이름 이름이 터널화될 수 있습니다.

delete (name)/create(name)
delete (name)/rename(source, name)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	fltkernel.h(Fltkernel.h 포함)
라이브러리	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL(반환 값 참조)