FltGetDestinationFileNameInformation 함수(fltkernel.h)

아티클
12/05/2023

FltGetDestinationFileNameInformation 루틴은 대상의 부모 디렉터리에 대한 파일 이름을 쿼리한 다음 이름이 변경되거나 NTFS 하드 링크가 만들어지는 파일 또는 디렉터리에 대한 전체 대상 경로 이름을 생성합니다.

구문

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

매개 변수

[in] Instance

파일이 있는 볼륨에 연결된 미니필터 드라이버 instance 대한 불투명 instance 포인터입니다.

[in] FileObject

파일의 파일 개체에 대한 포인터입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[in, optional] RootDirectory

링크 작업의 경우: 링크가 연결된 파일과 동일한 디렉터리에 만들거나 FileName 에 만들 링크의 전체 경로 이름이 포함된 경우 이 매개 변수는 NULL입니다. 그렇지 않으면 링크를 만들 디렉터리에 대한 핸들입니다.

이름 바꾸기 작업의 경우: 파일이 다른 디렉터리로 이동되지 않거나 FileName 에 전체 경로 이름이 포함된 경우 이 매개 변수는 NULL입니다. 그렇지 않으면 파일 이름이 변경된 후 상주하는 디렉터리에 대한 핸들입니다.

[in] FileName

링크 작업의 경우: 새로 만든 링크에 할당할 이름을 포함하는 와이드 문자열에 대한 포인터입니다.

이름 바꾸기 작업의 경우: 파일의 새 이름을 포함하는 와이드 문자열에 대한 포인터입니다.

[in] FileNameLength

FileName이 가리키는 와이드 문자열의 길이(바이트)입니다.

[in] NameOptions

반환할 이름 정보의 형식, 필터 관리자가 사용할 쿼리 메서드 및 추가 파일 이름 플래그를 지정하는 플래그가 포함된 FLT_FILE_NAME_OPTIONS 값입니다 . 이 매개 변수는 필수이며 NULL일 수 없습니다.

다음은 이름 형식 플래그 값입니다. 하나의 이름 형식 플래그만 지정할 수 있습니다. (FLT_FILE_NAME_SHORT 이 매개 변수에 유효한 플래그 값이 아닙니다.)

이름 형식 플래그 값	의미
FLT_FILE_NAME_NORMALIZED	FileName 매개 변수는 파일의 정규화된 대상 이름을 받습니다.
FLT_FILE_NAME_OPENED	FileName 매개 변수는 파일을 열 때 사용된 이름을 기반으로 파일의 대상 이름을 받습니다. 이 파일 이름은 정규화되지 않습니다.

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

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

다음은 파일 이름 플래그 값입니다. 이러한 플래그의 조합을 지정할 수 있습니다. FltGetDestinationFileNameNameInformation은 사후 생성 콜백에서 사용되지 않으므로 FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE 이 매개 변수에 대한 관련 플래그가 아닙니다.

파일 이름 플래그 값	의미
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation은 이름 요청을 호출 필터 instance 전달하여 완료합니다.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation 은 검색된 파일 이름을 캐시하지 않습니다. 이름 공급자 미니필터는 중간 쿼리를 수행하여 이름을 생성할 때 이 플래그를 사용합니다.

[out] RetFileNameInformation

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

반환 값

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

반환 코드	설명
STATUS_FLT_INVALID_NAME_REQUEST	이 값은 다음 이유 중 하나로 반환됩니다. (1) 현재 스레드의 TopLevelIrp 필드가 NULL이 아닌 경우 FltGetDestinationFileNameInformation에서 파일 이름 정보를 가져올 수 없습니다. 결과 파일 시스템 재귀로 인해 교착 상태 또는 스택 오버플로가 발생할 수 있기 때문입니다. (2) nameOptions 매개 변수의 이름 형식 플래그에 대해 FLT_FILE_NAME_SHORT 지정되었습니다.
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation 에서 풀 할당 오류가 발생했습니다. 오류 코드입니다.
STATUS_INVALID_PARAMETER	NameOptions 매개 변수에 잘못된 값이 지정되었습니다. 오류 코드입니다.
STATUS_MOUNT_POINT_NOT_RESOLVED	대상 경로 이름에는 파일이 있는 볼륨 이외의 볼륨으로 확인되는 탑재 지점이 포함되어 있습니다. (이름 바꾸기 또는 하드 링크 만들기 작업은 볼륨이 아닌 볼륨 내에서만 수행할 수 있으므로 작업이 실패합니다.) 오류 코드입니다.

설명

미니필터는 일반적으로 이름 바꾸기 또는 하드 링크 만들기 작업을 위해 사전 운용 콜백 루틴에서 FltGetDestinationFileNameInformation을 호출합니다. 즉, 대상 파일 이름이 존재하지 않을 가능성이 큽니다. "대상" 이름은 다음과 같습니다.

파일 이름 바꾸기의 경우 이름 바꾸기가 성공하면 파일 이름이 지정됩니다. 예를 들어 name1 의 이름을 name2로 바꾸는 경우 name2 는 대상 이름입니다.
하드 링크 만들기 작업의 경우 파일 시스템에 추가되는 이름입니다. 예를 들어 name1이라는 기존 파일에 hard link name2를 추가할 때 name2는 대상 이름입니다.

FltGetDestinationFileNameInformation 은 정규화된 파일 또는 "열린 파일" 형식으로 대상 파일 이름 정보를 반환합니다. 이러한 형식에 대한 자세한 내용은 FLT_FILE_NAME_INFORMATION 구조를 참조하세요.

FileObject 매개 변수에 대해 전달되는 파일 개체 포인터는 작업에 대한 FLT_RELATED_OBJECTS 구조의 FileObject 멤버이거나 작업에 대한 Data-Iopb-TargetFileObject>> 포인터여야 합니다. 여기서 Data는 작업의 콜백 데이터 구조(FLT_CALLBACK_DATA)입니다. 이 필드는 파일 시스템에서 균일하게 사용되지 않으므로 파일 개체 포인터는 Data-Iopb-Parameters.SetFileInformation.FileObject>> 멤버가 될 수 없습니다.

사용자가 파일 ID를 사용하여 파일을 열었지만 전체 경로에 대한 트래버스 권한이 없는 경우 FltGetDestinationFileNameInformation 은 사용자에게 권한이 있는 경로 부분만 반환합니다.

이름 바꾸기 또는 하드 링크 만들기 작업은 볼륨이 아닌 볼륨 내에서만 수행할 수 있습니다. 따라서 대상 경로 이름에 파일이 있는 볼륨 이외의 볼륨으로 확인되는 탑재 지점이 포함되어 있으면 이러한 작업이 실패합니다. 이름 바꾸기 작업에 대한 자세한 내용은 FILE_RENAME_INFORMATION 구조를 참조하세요. 하드 링크 만들기 작업에 대한 자세한 내용은 FILE_LINK_INFORMATION 구조를 참조하세요.

FltGetDestinationFileNameInformation을 성공적으로 호출한 후 호출자는 FltReleaseFileNameInformation을 호출하여 더 이상 필요하지 않은 경우 RetFileNameInformation 매개 변수에 반환된 포인터를 해제할 책임이 있습니다.

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

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

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

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

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