FltGetFileNameInformationUnsafe 함수(fltkernel.h)

아티클
02/06/2025

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

반환할 이름 정보의 형식과 필터 관리자에서 사용할 쿼리 메서드를 지정하는 플래그가 포함된 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 파일 이름 정보에 대한 필터 관리자의 이름 캐시를 쿼리합니다. 캐시에서 이름을 찾을 수 없으며 현재 안전한 경우 FltGetFileNameInformationUnsafe 파일 시스템에 파일 이름 정보를 쿼리하고 결과를 캐시합니다.

[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 이상의 경우 미니 필터에 DriverEntry 루틴과 같은 필터 인스턴스가 아직 없으면 Instance 매개 변수에 NULL 사용할 수 있습니다. 이렇게 하면 DriverEntry 루틴에서 파일 이름 정보에 액세스할 수 있습니다. 이 경우를 제외하고 인스턴스 매개 변수에 대한 NULL 값은 시스템 사용을 위해 예약되어 있습니다.

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

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