FltCreateFileEx2 함수(fltkernel.h)

아티클
02/05/2022
읽는 데 25분 걸림

미니 필터 드라이버는 FltCreateFileEx2 를 호출하여 새 파일을 만들거나 기존 파일을 엽니다. 이 루틴에는 선택적 ECP(create context 매개 변수)가 포함됩니다.

구문

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

매개 변수

[in] Filter

호출자에 대한 불투명 필터 포인터입니다.

[in, optional] Instance

만들기 요청을 보낼 미니 필터 드라이버 인스턴스에 대한 불투명 인스턴스 포인터입니다. 인스턴스는 파일 또는 디렉터리가 있는 볼륨에 연결되어야 합니다. 이 매개 변수는 선택 사항이며 NULL 일 수 있습니다. 이 매개 변수가 NULL 이면 요청이 볼륨에 대한 파일 시스템 드라이버 스택의 맨 위에 있는 디바이스 개체로 전송됩니다. 이 매개 변수가 NULL 이 아닌 경우 요청은 지정된 인스턴스 아래에 연결된 미니 필터 드라이버 인스턴스로만 전송됩니다.

[out] FileHandle

FltCreateFileEx2 에 대한 호출이 성공한 경우 파일 핸들을 받는 호출자 할당 변수에 대한 포인터입니다.

[out, optional] FileObject

FltCreateFileEx2 호출에 성공한 경우 파일 개체 포인터를 받는 호출자 할당 변수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL 일 수 있습니다.

[in] DesiredAccess

호출자에게 필요한 파일 또는 디렉터리에 대한 액세스 유형을 지정하는 플래그의 비트 마스크입니다. 이 매개 변수에 대한 자세한 내용과 플래그 값 목록은 IoCreateFileEx의 DesiredAccess 매개 변수를 참조하세요.

[in] ObjectAttributes

InitializeObjectAttributes를 사용하여 이미 초기화된 불투명 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 자세한 내용 및 각 구조체 멤버에 대한 설명은 IoCreateFileEx의 ObjectAttributes 매개 변수를 참조하세요.

[out] IoStatusBlock

요청된 작업에 대한 최종 완료 상태 및 정보를 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터입니다. 이 매개 변수에 대한 자세한 내용은 IoCreateFileEx의 IoStatusBlock 매개 변수를 참조하세요.

[in, optional] AllocationSize

필요에 따라 파일 스트림에 대한 초기 할당 크기(바이트)를 지정합니다. 파일을 만들거나 덮어쓰거나 대체하지 않는 한 0이 아닌 값은 적용되지 않습니다.

[in] FileAttributes

파일을 만들거나 대체하거나 덮어쓰는 경우 설정할 파일 특성을 나타내는 하나 이상의 FILE_ATTRIBUTE_ XXX 플래그를 지정합니다. 자세한 내용 및 플래그 목록은 IoCreateFileEx의 FileAttributes 매개 변수를 참조하세요.

[in] ShareAccess

호출자가 필요로 하는 파일에 대한 공유 액세스 유형을 0개 또는 1개 또는 플래그 조합으로 지정합니다. 자세한 내용 및 플래그 목록은 IoCreateFileEx의 ShareAccess 매개 변수를 참조하세요.

[in] CreateDisposition

파일이 이미 있는지 여부에 따라 수행할 작업을 결정하는 값을 지정합니다. 가능한 값 목록은 IoCreateFileEx의 Disposition 매개 변수를 참조하세요.

[in] CreateOptions

파일을 만들거나 열 때 적용할 옵션을 지정합니다. 이 매개 변수는 IoCreateFileEx의 CreateOptions 매개 변수에 나열되고 설명된 플래그의 호환 가능한 조합입니다.

[in, optional] EaBuffer

파일에 적용할 EA(확장 특성) 정보가 포함된 호출자 제공 FILE_FULL_EA_INFORMATION 버퍼에 대한 포인터입니다.

[in] EaLength

EaBuffer 의 길이(바이트)입니다.

[in] Flags

만들기 요청을 만드는 동안 사용할 옵션을 지정합니다. 가능한 옵션 목록은 IoCreateFileEx 의 Options 매개 변수를 참조하세요.

[in, optional] DriverContext

IoInitializeDriverCreateContext에 의해 이미 초기화된 IO_DRIVER_CREATE_CONTEXT 구조체에 대한 선택적 포인터입니다.

반환 값

FltCreateFileEx2 는 STATUS_SUCCESS 또는 적절한 NTSTATUS 값을 반환합니다. 가능한 반환 코드 목록은 IoCreateFileEx의 반환 값 섹션을 참조하세요.

참고

FltCreateFileEx2 는 STATUS_FILE_LOCK_CONFLICT 반환 값 또는 IoStatusBlock 매개 변수가 가리키는 IO_STATUS_BLOCK 구조체의 Status 멤버로 반환할 수 있습니다. NTFS 로그 파일이 가득 차서 FltCreateFileEx2 가 이 상황을 처리하려고 시도하는 동안 오류가 발생하는 경우에만 발생합니다.

설명

FltCreateFileEx2 는 DriverContext 입력 매개 변수를 지원한다는 점을 제외하고 FltCreateFile 및 FltCreateFileEx와 비슷합니다.

만들기 작업의 일부로 ECP를 지정하려면 FltAllocateExtraCreateParameterList 루틴을 사용하여 IO_DRIVER_CREATE_CONTEXT 구조체의 ExtraCreateParameter 멤버를 초기화합니다. ECP를 사용하는 경우 적절한 루틴을 사용하여 생성, 조작 및 해제해야 합니다.

FltCreateFileEx2 호출자 아래의 필터 드라이버는 호출자에 ECP를 추가하거나 삭제하면 안 됩니다. 따라서 FltCreateFileEx2 호출에서 돌아오면 ECP 목록은 변경되지 않아야 하며 다른 만들기 작업을 위해 FltCreateFileEx2 의 추가 호출에 전달될 수 있습니다. 운영 체제는 ECP 목록 구조의 할당을 자동으로 취소하지 않습니다. FltCreateFileEx2 의 호출자는 FltFreeExtraCreateParameterList 루틴을 호출하여 이 구조체의 할당을 취소해야 합니다.

트랜잭션 컨텍스트에서 파일을 만들거나 열려면 IO_DRIVER_CREATE_CONTEXT 구조체의 TxnParameters 멤버를 IoGetTransactionParameterBlock 루틴에서 반환된 값으로 설정합니다.

FltCreateFileEx2 는 지정된 미니 필터 드라이버 인스턴스 아래에 연결된 인스턴스와 파일 시스템에만 만들기 요청을 보냅니다. 지정된 인스턴스와 위에 연결된 인스턴스는 만들기 요청을 받지 않습니다. 인스턴스를 지정하지 않으면 요청이 스택의 맨 위로 이동하고 모든 인스턴스 및 파일 시스템에서 수신됩니다.

FltCreateFileEx2 를 사용하여 만들거나 열 파일의 이름을 지정하는 두 가지 다른 방법이 있습니다.

입력 ObjectAttributes 의 ObjectName 멤버에 제공된 정규화된 경로 이름입니다.
입력 ObjectAttributes 의 RootDirectory 멤버에 있는 핸들이 나타내는 디렉터리 파일을 기준으로 하는 경로 이름입니다.

FltCreateFileEx2 에서 가져온 모든 FileHandle 은 결국 FltClose를 호출하여 해제해야 합니다. 또한 ObDereferenceObject를 호출하여 더 이상 필요하지 않은 경우 반환된 FileObject 포인터를 역참조해야 합니다.

시스템 프로세스 컨텍스트에서 실행되지 않는 드라이버 루틴은 FltCreateFileEx2 의 ObjectAttributes 매개 변수에 대한 OBJ_KERNEL_HANDLE 특성을 설정해야 합니다. 이 특성을 설정하면 FltCreateFileEx2 에서 반환되는 핸들의 사용이 커널 모드에서 실행되는 프로세스로 제한됩니다. 그렇지 않으면 드라이버가 실행 중인 컨텍스트의 프로세스에서 핸들에 액세스할 수 있습니다.

참고

시스템 교착 상태가 발생할 수 있으므로 NULL이 아닌 최상위 IRP 값으로 이 루틴을 호출하지 마세요.

특정 DesiredAccess 플래그 및 플래그 조합에는 다음과 같은 효과가 있습니다.

반환된 FileHandle 이 신호됨 상태로 설정될 때까지 대기하여 호출자가 I/O 완료를 동기화하려면 SYNCHRONIZE 플래그를 설정해야 합니다.
FILE_APPEND_DATA 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 파일의 끝에만 쓸 수 있으며 파일에 대한 쓰기 요청에 대한 오프셋 정보는 무시됩니다. 그러나 이 유형의 쓰기 작업에 필요한 경우 파일이 자동으로 확장됩니다.
파일에 대한 FILE_WRITE_DATA 플래그를 설정하면 파일의 끝 이후의 쓰기 요청도 발생할 수 있습니다. 파일은 이러한 유형의 쓰기 요청에 대해서도 자동으로 확장됩니다.
FILE_EXECUTE 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 FileHandle 매개 변수에 반환된 핸들을 사용하여 파일을 직접 읽거나 파일에서 데이터를 쓸 수 없습니다. 즉, 파일의 모든 작업은 시스템 페이징 I/O를 사용하여 파일 데이터를 읽거나 써야 합니다.

ShareAccess 매개 변수는 별도의 스레드가 동일한 파일에 동시에 액세스할 수 있는지 여부를 결정합니다. 두 파일 오프너 모두 지정된 방식으로 파일에 액세스할 수 있는 권한이 있는 경우 파일을 성공적으로 열고 공유할 수 있습니다. FltCreateFileEx2 의 원래 호출자가 FILE_SHARE_READ, FILE_SHARE_WRITE 또는 FILE_SHARE_DELETE 지정하지 않으면 원래 호출자에게 파일에 대한 단독 액세스 권한이 부여되기 때문에 파일에 대해 다른 열린 작업을 수행할 수 없습니다.

공유 파일을 성공적으로 열려면 파일에 대한 요청 된 DesiredAccess 가 FltClose에서 아직 릴리스되지 않은 모든 이전 열린 요청의 DesiredAccess 및 ShareAccess 사양과 호환되어야 합니다. 즉, 지정된 파일에 대해 FltCreateFileEx2 에 지정된 DesiredAccess 매개 변수는 파일의 다른 오프너가 허용하지 않은 액세스와 충돌해서는 안 됩니다.

참고

Flags 매개 변수에 IO_IGNORE_SHARE_ACCESS_CHECK 지정되면 I/O 관리자는 ShareAccess 매개 변수를 무시합니다. 그러나 파일 시스템은 여전히 액세스 검사를 수행할 수 있습니다. 따라서 IO_IGNORE_SHARE_ACCESS_CHECK 플래그를 사용하는 경우에도 ShareAccessparameter 에 대해 원하는 공유 모드를 지정하는 것이 중요합니다. 또한 IO_IGNORE_SHARE_ACCESS_CHECK 지정되면 파일 시스템은 현재 열려 있는 액세스 또는 공유 액세스를 추적하지 않습니다. 이 때문에 동일한 파일에 대한 후속 열기 호출이 성공할 수 있습니다.

CreateDisposition 값 FILE_SUPERSEDE 호출자에게 기존 파일 개체에 대한 DELETE 액세스 권한이 있어야 합니다. 이 경우 기존 파일의 FILE_SUPERSEDE 사용하여 FltCreateFileEx2 를 성공적으로 호출하면 해당 파일이 효과적으로 삭제된 다음 다시 만들어집니다. 이는 파일이 이미 다른 스레드에서 열려 있는 경우 FILE_SHARE_DELETE 플래그가 설정된 ShareAccessparameter 를 지정하여 파일을 열었다는 것을 의미합니다. 이러한 유형의 처리는 파일을 덮어쓰는 POSIX 스타일과 일치합니다.

createDisposition 값 FILE_OVERWRITE_IF 및 FILE_SUPERSEDE 비슷합니다. FltCreateFileEx2 가 기존 파일과 이러한 CreateDisposition 값 중 하나를 사용하여 호출되면 파일이 대체됩니다.

다음을 제외하고 파일을 덮어쓰는 것은 의미상 대체 작업과 동일합니다.

호출자는 액세스 권한을 삭제하는 대신 파일에 대한 쓰기 권한이 있어야 합니다. 이는 파일이 이미 다른 스레드에서 열려 있는 경우 입력 ShareAccess 매개 변수에 설정된 FILE_SHARE_WRITE 플래그를 사용하여 파일을 열었다는 것을 의미합니다.
지정된 파일 특성은 비트 OR 연산을 사용하여 파일에 이미 적용된 특성과 결합됩니다. 이는 파일이 다른 스레드에서 이미 열려 있는 경우 FltCreateFileEx2 의 후속 호출자가 기존 FileAttributes 플래그를 사용하지 않도록 설정할 수 없지만 동일한 파일에 대해 추가 플래그를 사용하도록 설정할 수 있음을 의미합니다. 이 파일 덮어쓰기 스타일은 MS-DOS, Windows 3.1 및 OS/2와 일치합니다.

CreateOptions FILE_DIRECTORY_FILE 값은 만들거나 열 파일이 디렉터리 파일임을 지정합니다. 디렉터리 파일을 만들 때 파일 시스템은 디스크에 해당 특정 파일 시스템의 디스크 구조에 대한 빈 디렉터리를 나타내는 적절한 구조를 만듭니다. 이 옵션을 지정하고 열 지정된 파일이 디렉터리 파일이 아니거나 호출자가 일관성 없는 CreateOptions 또는 CreateDisposition 값을 지정한 경우 FltCreateFileEx2에 대한 호출이 실패합니다.

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 플래그를 사용하면 파일 시스템이 호출자를 대신하여 중간 버퍼링을 수행할 수 없습니다. 이 값을 지정하면 호출자의 매개 변수에 대한 특정 제한이 다른 Flt.에 배치됩니다. 파일 루틴 또는 Zw. 다음 을 포함한 파일 루틴:

FltReadFile, ZwReadFile, FltWriteFile 또는 ZwWriteFile의 ByteOffset 매개 변수에 전달된 바이트 오프 셋 값은 섹터 크기의 배수여야 합니다.
FltReadFile, ZwReadFile, FltWriteFile 또는 ZwWriteFile에 전달된 Length 매개 변수는 섹터 크기의 배수여야 합니다. 길이가 정확히 섹터 크기인 버퍼에 읽기 작업을 지정하면 전송 중에 파일의 끝에 도달한 경우 해당 버퍼로 전송되는 중요한 바이트가 줄어들 수 있습니다.
버퍼는 기본 스토리지 디바이스의 맞춤 요구 사항에 따라 정렬되어야 합니다. 이 정보는 FltCreateFileEx2 를 호출하여 물리적 디바이스를 나타내는 파일 개체에 대한 핸들을 가져온 다음 해당 핸들을 사용하여 ZwQueryInformationFile 을 호출하고 FileAlignmentInformation 을 FileInformationClass 매개 변수의 값으로 지정하여 가져올 수 있습니다. Ntifs.h 에 정의된 시스템 FILE_ XXX _ALIGNMENT 값에 대한 자세한 내용은 DEVICE_OBJECT 및 디바이스 개체 초기화를 참조하세요.
FileInformationClass 매개 변수가 FilePositionInformation으로 설정된 FltSetInformationFile 또는 ZwSetInformationFile에 대한 호출은 섹터 크기의 배수인 오프셋을 지정해야 합니다.

CreateOptions FILE_SYNCHRONOUS_IO_ALERT 및 FILE_SYNCHRONOUS_IO_NONALERT 플래그는 이름에 따라 상호 배타적이며, 동기 I/O를 위해 파일을 열도록 지정합니다. 즉, 반환된 FileHandle 이 참조하는 파일 개체를 통해 발생하는 한 파일에 대한 모든 I/O 작업이 동기적이어야 합니다. 이러한 파일의 모든 I/O는 반환된 핸들을 사용하여 모든 스레드에서 serialize됩니다. 이러한 CreateOptions 플래그 중 하나를 설정하면 I/O 관리자는 파일 개체의 CurrentByteOffset 필드에서 현재 파일 위치 오프셋을 유지 관리합니다. 이 오프셋은 ZwReadFile 및 ZwWriteFile 호출에 사용할 수 있습니다. ZwQueryInformationFile 또는 ZwSetInformationFile을 호출하여 쿼리하거나 설정할 수도 있습니다.

CreateOptions FILE_OPEN_REPARSE_POINT 플래그를 지정 하지 않고 FltCreateFileEx2 가 재분석 지점이 있는 파일을 열려고 하면 파일에 대해 일반적인 재분석 지점 처리가 수행됩니다. 반면에 FILE_OPEN_REPARSE_POINT 플래그가 지정된 경우 정상적인 재문 분석 처리가 발생하지 않고 FltCreateFileEx2 에서 재문 분석 지점 파일을 직접 열려고 시도합니다. 두 경우 모두 열기 작업이 성공하면 FltCreateFileEx2 는 STATUS_SUCCESS; 그렇지 않으면 루틴은 NTSTATUS 오류 코드를 반환합니다. FltCreateFileEx2 는 STATUS_REPARSE 반환하지 않습니다.

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 플래그는 파일을 열고 제3자가 파일을 열고 공유 위반을 받을 수 있는 oplock을 요청하는 시점 사이의 시간을 제거합니다. 애플리케이션은 FltCreateFileEx2 에서 FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용한 다음 모든 oplock을 요청할 수 있습니다. 이렇게 하면 공유 위반을 일으키는 나중에 열려 있는 요청에 대해 oplock 소유자에게 알림이 전송됩니다.

Windows 7에서 애플리케이션이 FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용할 때 다른 핸들이 파일에 있으면 만들기 작업이 STATUS_OPLOCK_NOT_GRANTED 함께 실패합니다. 이 제한은 더 이상 Windows 8 시작되지 않습니다.

이 만들기 작업이 파일에 이미 있는 oplock을 중단하는 경우 FILE_OPEN_REQUIRING_OPLOCK 플래그를 설정하면 만들기 작업이 STATUS_CANNOT_BREAK_OPLOCK 실패합니다. 이 만들기 작업으로 인해 기존 oplock이 끊어지지 않습니다.

이 플래그를 사용하는 애플리케이션은 이 호출이 성공한 후 oplock을 요청해야 합니다. 또는 이후의 모든 파일 열기 시도는 일반적인 oplock 처리의 이점 없이 차단됩니다. 마찬가지로 이 호출이 성공하지만 이후 oplock 요청이 실패하는 경우 이 플래그를 사용하는 애플리케이션은 oplock 요청이 실패했음을 감지한 후 핸들을 닫아야 합니다.

참고

FILE_OPEN_REQUIRING_OPLOCK 플래그는 Windows 7, Windows Server 2008 R2 이상 Windows 운영 체제에서 사용할 수 있습니다. Windows 7에서 이 플래그를 구현하는 Microsoft 파일 시스템은 NTFS, FAT 및 exFAT입니다.

CreateOptions 플래그 FILE_RESERVE_OPFILTER 사용하면 애플리케이션이 수준 1, 일괄 처리 또는 필터 oplock을 요청하여 다른 애플리케이션이 공유 위반을 가져오지 못하도록 할 수 있습니다. 그러나 FILE_RESERVE_OPFILTER 필터 oplock에만 실질적으로 유용합니다. 이를 사용하려면 다음 단계를 완료해야 합니다.

FILE_RESERVE_OPFILTER CreateOptions, 정확히 FILE_READ_ATTRIBUTES DesiredAccess 및 정확히 FILE_SHARE_READ | ShareAccess 를 사용하여 만들기 요청을 실행합니다. FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- 열려 있는 핸들이 이미 있는 경우 STATUS_OPLOCK_NOT_GRANTED 함께 만들기 요청이 실패하고 다음 요청된 oplock도 실패합니다.
- 더 많은 액세스 권한 또는 더 적은 공유로 열면 STATUS_OPLOCK_NOT_GRANTED 오류가 발생합니다.
만들기 요청이 성공하면 oplock을 요청합니다.
파일에 대한 다른 핸들을 열어 I/O를 수행합니다.

NTFS는 FILE_RESERVE_OPFILTER 구현하는 유일한 Microsoft 파일 시스템입니다.

미니 필터 드라이버는 파일 이름을 바꾸려면 ZwSetInformationFile이 아닌 FltSetInformationFile을 사용해야 합니다.

참고

볼륨을 열려고 하지만 DesiredAccess 매개 변수에 대해 다음 플래그의 조합만 지정하면 FltCreateFileEx2 는 볼륨에 대한 스토리지 디바이스에 직접 액세스할 수 있는 파일 시스템과는 별개로 핸들을 엽니다.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

FltCreateFileEx2 를 사용하여 볼륨에 대한 스토리지 디바이스에 직접 액세스할 수 있는 핸들을 열거나 시스템 리소스를 누수해서는 안 됩니다. 스토리지 디바이스에 직접 액세스할 수 있는 핸들을 열려면 IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint 또는 ZwCreateFile 함수를 대신 호출합니다.

FltCreateFileEx2 호출자가 볼륨 대상에 대해 재구매를 사용하도록 설정하려는 경우 FLT_CREATEFILE_TARGET_ECP_CONTEXT DriverContext 매개 변수의 ECP 목록에 대한 ECP로 포함될 수 있습니다. 이 ECP가 있는 경우 FltCreateFileEx2 는 만들기 작업에 대한 대상 디바이스를 조정하고 지정된 파일 정보에 적합한 볼륨의 필터링된 인스턴스를 찾으려고 시도합니다. 이 ECP의 사용은 Windows 8부터 사용할 수 있습니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	fltkernel.h(FltKernel.h 포함)
라이브러리	Fltmgr.lib
IRQL	PASSIVE_LEVEL