PFLT_NORMALIZE_NAME_COMPONENT_EX 콜백 함수(fltkernel.h)

아티클
08/07/2023

필터 관리자의 이름 캐시에 대한 파일 이름을 제공하는 미니필터 드라이버는 PFLT_NORMALIZE_NAME_COMPONENT_EX 형식의 루틴을 미니필터 드라이버의 NormalizeNameComponentExCallback 콜백 루틴으로 등록할 수 있습니다.

구문

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

매개 변수

[in] Instance

이 콜백 루틴이 등록된 미니필터 드라이버 instance 대한 불투명 instance 포인터입니다.

[in] FileObject

이름이 요청되는 파일의 파일 개체 또는 FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME 플래그가 설정된 경우 IRP_MJ_SET_INFORMATION 작업의 대상인 파일에 대한 포인터입니다. 자세한 내용은 아래 Flags 매개 변수를 참조하세요.

[in] ParentDirectory

이 이름 구성 요소에 대한 부모 디렉터리의 이름을 포함하는 UNICODE_STRING 구조체에 대한 포인터입니다.

[in] VolumeNameLength

ParentDirectory 매개 변수가 가리키는 구조체에 저장된 부모 디렉터리 이름의 길이(바이트)입니다.

[in] Component

확장할 이름 구성 요소가 포함된 UNICODE_STRING 구조체에 대한 포인터입니다.

[out] ExpandComponentName

이름 구성 요소에 대한 확장(정규화된) 파일 이름 정보를 수신하는 FILE_NAMES_INFORMATION 구조체에 대한 포인터입니다.

[in] ExpandComponentNameLength

ExpandComponentName 매개 변수가 가리키는 버퍼의 길이(바이트)입니다.

[in] Flags

이름 정규화 플래그입니다. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE 정규화할 이름이 대/소문자를 구분하도록 지정합니다. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME FltGetDestinationFileNameInformation 루틴 호출을 서비스하기 위해 콜백 루틴이 호출되었음을 지정합니다. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME 플래그가 설정되면 FileObject 는 IRP_MJ_SET_INFORMATION 작업의 대상인 파일/디렉터리를 나타냅니다. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME 플래그가 설정되지 않은 경우 FileObject 는 이름이 요청되는 파일/디렉터리를 나타냅니다.

[in, out] NormalizationContext

동일한 파일 이름 경로의 나머지 구성 요소를 정규화하기 위해 만들어진 이 콜백 루틴에 대한 후속 호출에서 전달될 미니필터 드라이버 제공 컨텍스트 정보에 대한 포인터입니다.

반환 값

이 콜백 루틴은 STATUS_SUCCESS 또는 적절한 NTSTATUS 값을 반환합니다. Component 매개 변수가 지정하는 이름 구성 요소가 ParentDirectory 매개 변수가 지정하는 부모 디렉터리에 없는 경우 이 콜백 루틴은 STATUS_NO_SUCH_FILE 반환해야 합니다. 이 콜백 루틴이 부모 디렉터리에 대한 IRP_MN_QUERY_DIRECTORY(FileNamesInformation) 요청을 발급하는 경우 파일 시스템은 올바른 상태 코드를 반환합니다. 이 경우 이 콜백은 파일 시스템에서 반환하는 상태 코드를 반환할 수 있습니다.

설명

NormalizeNameComponentExCallback 콜백 루틴과 NormalizeNameComponentCallback 콜백 루틴(PFLT_NORMALIZE_NAME_COMPONENT 형식)의 주요 차이점은 NormalizeNameComponentExCallback 콜백 루틴이 추가 FileObject 매개 변수를 지원한다는 것입니다. 파일 개체(FileObject)는 미니필터 드라이버에서 IoGetTransactionParameterBlock 루틴을 호출하여 파일/디렉터리가 참여하는 작업에 대한 TXN_PARAMETER_BLOCK 구조를 검색하는 데 사용할 수 있습니다. TXN_PARAMETER_BLOCK 구조체는 미니필터 드라이버가 이 파일 개체가 참여하는 트랜잭션의 컨텍스트에서 자체 만들기 요청을 발급하는 데 사용할 수 있습니다.

이 콜백 루틴을 등록하기 위해 미니필터 드라이버는 미니필터 드라이버가 FltRegisterFilter에 매개 변수로 전달하는 FLT_REGISTRATION 구조체의 NormalizeNameComponentExCallback 멤버에 PFLT_NORMALIZE_NAME_COMPONENT_EX 형식의 루틴 주소를 저장합니다.

필터 관리자는 이 콜백 루틴을 호출하여 미니필터 드라이버의 이름이 수정된 파일 이름 경로의 구성 요소에 대한 정규화된 이름을 미니필터 드라이버에 쿼리합니다. 파일 이름 경로에 두 개 이상의 구성 요소가 포함된 경우 필터 관리자는 경로의 모든 구성 요소를 정규화하는 과정에서 이 콜백 루틴을 여러 번 호출할 수 있습니다. 미니필터 드라이버는 NormalizationContext 매개 변수를 사용하여 컨텍스트 정보를 이 콜백 루틴에 대한 후속 호출에 전달할 수 있습니다.

미니필터 드라이버가 NormalizationContext 매개 변수를 사용하는 경우 정규화 컨텍스트 정리 콜백 루틴도 등록해야 합니다. 자세한 내용은 PFLT_NORMALIZE_CONTEXT_CLEANUP 대한 참조 항목을 참조하세요.