FltGetFileNameInformationUnsafe 함수(fltkernel.h)

아티클
08/07/2023

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

구문

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

매개 변수

[in] FileObject

파일 또는 디렉터리에 대한 파일 개체에 대한 포인터입니다. 파일 개체는 현재 열려 있어야 합니다. 이 매개 변수는 필수이며 NULL로 설정할 수 없습니다.

[in, optional] Instance

호출자에 대한 인스턴스 포인터입니다. 이 매개 변수는 NULL로 설정할 수 있습니다.

[in] NameOptions

반환할 이름 정보의 형식과 Filter Manager에서 사용할 쿼리 메서드를 지정하는 플래그가 포함된 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자까지 추가됩니다. 파일의 짧은 이름에는 볼륨 이름, 디렉터리 경로 또는 스트림 이름이 포함되지 않습니다.

다음 표에서는 쿼리 메서드 플래그 값에 대해 설명합니다. 플래그 중 하나만 지정할 수 있습니다.

값	의미
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe 는 파일 이름 정보에 대해 필터 관리자의 이름 캐시를 쿼리합니다. 캐시에서 이름을 찾을 수 없는 경우 FltGetFileNameInformationUnsafe 는 파일 시스템을 쿼리하고 결과를 캐시합니다.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe 는 파일 이름 정보에 대해 필터 관리자의 이름 캐시를 쿼리합니다. FltGetFileNameInformationUnsafe 는 파일 시스템을 쿼리하지 않습니다.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe 는 파일 시스템에 파일 이름 정보를 쿼리합니다. FltGetFileNameInformationUnsafe 는 필터 관리자의 이름 캐시를 쿼리하지 않으며 파일 시스템 쿼리의 결과를 캐시하지 않습니다.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe 는 파일 이름 정보에 대해 필터 관리자의 이름 캐시를 쿼리합니다. 캐시에서 이름을 찾을 수 없으며 현재 안전한 경우 FltGetFileNameNameInformationUnsafe 는 파일 시스템에 파일 이름 정보를 쿼리하고 결과를 캐시합니다.

[out] FileNameInformation

시스템이 할당한 FLT_FILE_NAME_INFORMATION 구조체의 주소를 수신하는 호출자가 할당한 변수에 대한 포인터입니다. FltGetFileNameInformationUnsafe 는 페이징된 풀에서 이 구조를 할당합니다. 이 정보가 더 이상 필요하지 않은 경우 호출자는 FltReleaseFileNameInformation을 호출하여 구조를 해제해야 합니다. 이 매개 변수는 필수이며 NULL로 설정할 수 없습니다.

반환 값

FltGetFileNameInformationUnsafe 는 STATUS_SUCCESS 또는 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.

반환 코드	설명
STATUS_FLT_INVALID_NAME_REQUEST	FileObject 매개 변수가 가리키는 파일 개체가 현재 열려 있지 않습니다. 오류 코드입니다.
STATUS_INVALID_PARAMETER	FileNameInformation 매개 변수에 대해 잘못된 값이 전달되었습니다. 오류 코드입니다.

설명

FltGetFileNameInformationUnsafe 루틴은 해당 파일 개체에 대한 I/O 작업의 컨텍스트 외부에서 파일 개체의 이름을 쿼리할 수 있도록 제공됩니다. 그렇지 않으면 FltGetFileNameInformation을 호출해야 합니다.

FltGetFileNameInformation 루틴과 달리 FltGetFileNameInformationUnsafe는 파일 시스템에서 이름 정보를 쿼리하면 FLT_FILE_NAME_QUERY_CACHE_ONLY 이외의 쿼리 메서드에 교착 상태가 발생할 수 있는 다음과 같은 유형의 상황에 대해 호출자를 보호하지 않습니다.

페이징 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를 반환하는 경우입니다.

Windows Vista/Server 2008 이상에서는 Minifilter에 DriverEntry 루틴과 같은 필터 instance 아직 없는 경우 Instance 매개 변수에 사용할 NULL 수 있습니다. 이렇게 하면 DriverEntry 루틴에서 파일 이름 정보에 액세스할 수 있습니다. 이 경우 NULL 를 제외하고 instance 매개 변수의 값은 시스템 사용을 위해 예약됩니다.

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

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

요구 사항

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