FltReadFileEx 함수(fltkernel.h)

FltReadFileEx 는 열려 있는 파일, 스트림 또는 디바이스에서 데이터를 읽습니다. 이 함수는 FltReadFile 을 확장하여 매핑된 버퍼 주소 대신 읽기 데이터에 MDL을 선택적으로 사용할 수 있도록 합니다.

구문

NTSTATUS FLTAPI FltReadFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [out]           PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesRead,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

매개 변수

[in] InitiatingInstance

작업을 보낼 미니필터 드라이버 instance 대한 불투명 instance 포인터입니다. instance 파일이 있는 볼륨에 연결해야 합니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[in] FileObject

데이터를 읽을 파일의 FILE_OBJECT 대한 포인터입니다. 이 파일 개체는 현재 열려 있어야 합니다. 파일 개체가 아직 열려 있지 않거나 더 이상 열려 있지 않을 때(예: 사전 만들기 또는 정리 후 콜백 루틴에서) FltReadFileEx 를 호출하면 시스템이 확인된 빌드에서 ASSERT가 됩니다. 이 매개 변수는 필수이며 NULL일 수 없습니다.

[in, optional] ByteOffset

읽기 작업을 시작할 파일 내의 시작 바이트 오프셋을 지정하는 호출자 할당 변수에 대한 포인터입니다.

ByteOffset을 지정하면 파일 개체의 CurrentByteOffset 필드의 현재 값에 관계없이 해당 오프셋에서 I/O가 수행됩니다.

• 파일 개체의 Flags 필드에 FO_SYNCHRONOUS_IO 동기 I/O용으로 파일을 연 경우 호출자는 ByteOffset-LowPart>를 FILE_USE_FILE_POINTER_POSITION, ByteOffset-HighPart>를 -1로 설정하여 파일 개체의 CurrentByteOffset 필드에서 I/O를 수행할 수 있습니다.
• 파일이 동기 I/O용으로 열리지 않은 경우 FILE_USE_FILE_POINTER_POSITION 사용하는 것은 오류입니다.

ByteOffset이 지정되지 않은 경우:

• 파일이 동기 I/O용으로 열리지 않은 경우 이는 오류입니다.
• 그렇지 않으면 파일 개체의 CurrentByteOffset에서 I/O가 수행됩니다.

동기 I/O에 대해 파일 개체를 연 경우 호출자가 FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET 플래그를 전달하지 않는 한 CurrentByteOffset 필드가 업데이트됩니다.

• 참고: 이 경우 파일 시스템은 CurrentByteOffset 을 계속 업데이트합니다. 필터 관리자는 I/O를 스택 아래로 보내기 전에 CurrentByteOffset 값을 저장하고 I/O가 반환되면 복원합니다. FltReadFileEx 호출자(및 더 높은 고도의 필터)의 관점에서 CurrrentByteOffset은 업데이트되지 않습니다. 그러나 호출자 아래의 필터는 읽기/쓰기 후 콜백에서 업데이트된 CurrentByteOffset 값을 확인합니다.

동기 I/O에 대해 파일 개체가 열리지 않은 경우 ByteOffset 매개 변수의 상태에 관계없이 CurrentByteOffset 필드가 업데이트되지 않습니다.

[in] Length

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

[out] Buffer

파일에서 읽은 데이터를 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다. MDL이 Mdl에 제공된 경우 버퍼는 NULL이어야 합니다.

[in] Flags

수행할 읽기 작업의 유형을 지정하는 플래그의 비트 마스크입니다.

[out, optional] BytesRead

파일에서 읽은 바이트 수를 수신하는 호출자가 할당한 변수에 대한 포인터입니다. CallbackRoutine이 NULL이 아닌 경우 이 매개 변수는 무시됩니다. 그렇지 않으면 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, optional] CallbackRoutine

읽기 작업이 완료된 경우 호출할 PFLT_COMPLETED_ASYNC_IO_CALLBACK 형식의 콜백 루틴에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, optional] CallbackContext

CallbackRoutine에 전달될 컨텍스트 포인터(있는 경우)입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. CallbackRoutine이 NULL인 경우 이 매개 변수는 무시됩니다.

[in, optional] Key

바이트 범위 잠금과 연결된 선택적 키입니다.

[in, optional] Mdl

데이터를 읽는 메모리를 설명하는 선택적 MDL입니다. 버퍼 에 버 퍼 가 제공되면 Mdl 은 NULL이어야 합니다.

반환 값

FltReadFileEx 는 파일 시스템에서 반환된 NTSTATUS 값을 반환합니다.

설명

미니필터 드라이버는 FltReadFileEx 를 호출하여 열려 있는 파일에서 데이터를 읽습니다.

FltReadFileEx는 읽기 요청을 만들고 시작 instance 아래에 연결된 미니필터 드라이버 인스턴스와 파일 시스템으로 보냅니다. 지정된 instance 위에 연결된 인스턴스는 읽기 요청을 받지 않습니다.

FltReadFileEx 는 다음 중 하나가 true인 경우 캐시되지 않은 I/O를 수행합니다.

• 호출자는 Flags 매개 변수에서 FLTFL_IO_OPERATION_NON_CACHED 플래그를 설정합니다.

• 캐시되지 않은 I/O에 대해 파일 개체가 열렸습니다. 일반적으로 이 작업은 FltCreateFile, FltCreateFileEx 또는 ZwCreateFile에 대한 이전 호출에서 FILE_NO_INTERMEDIATE_BUFFERING CreateOptions 플래그를 지정하여 수행됩니다.

캐시되지 않은 I/O는 FltReadFileEx에 전달된 매개 변수 값에 다음과 같은 제한을 적용합니다.

• Buffer 매개 변수가 가리키는 버퍼는 기본 스토리지 디바이스의 맞춤 요구 사항에 따라 정렬되어야 합니다. 정렬된 버퍼를 할당하려면 FltAllocatePoolAlignedWithTag를 호출합니다.

• ByteOffset 매개 변수가 가리키는 바이트 오프셋은 볼륨 섹터 크기의 음수가 아닌 배수여야 합니다.

• Length 매개 변수에 지정된 길이는 볼륨 섹터 크기의 음수가 아닌 배수여야 합니다.

파일의 끝부분에서 읽기를 시도하면 FltReadFileEx 에서 오류가 반환됩니다.

CallbackRoutine 매개 변수의 값이 NULL이 아니면 읽기 작업이 비동기적으로 수행됩니다.

CallbackRoutine 매개 변수의 값이 NULL이면 읽기 작업이 동기적으로 수행됩니다. 즉, FltReadFileEx 는 읽기 작업이 완료될 때까지 기다렸다가 반환합니다. FileObject가 가리키는 파일 개체가 비동기 I/O에 대해 열린 경우에도 마찬가지입니다.

여러 스레드가 동일한 파일 개체에 대해 FltReadFileEx 를 호출하고 동기 I/O를 위해 파일 개체를 연 경우 필터 관리자는 파일에서 I/O를 직렬화하려고 시도하지 않습니다. 이와 관련하여 FltReadFileEx 는 ZwReadFile과 다릅니다.

Mdl 매개 변수는 미니필터에 이미 MDL을 사용할 수 있는 경우 편의를 위해 제공됩니다. MDL은 직접 사용되며 버퍼 에 대한 주소를 매핑하는 추가 단계를 방지할 수 있습니다.

요구 사항

추가 정보

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltWriteFile

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile