FltReadFile 함수(fltkernel.h)

아티클
02/06/2025

FltReadFile 열려 있는 파일, 스트림 또는 디바이스에서 데이터를 읽습니다.

통사론

NTSTATUS FLTAPI FltReadFile(
  [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] InitiatingInstance

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

[in] FileObject

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

[in, optional] ByteOffset

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

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

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

ByteOffset 지정되지 않은 경우:

파일이 동기 I/O용으로 열리지 않은 경우 오류가 발생합니다.
그렇지 않으면 파일 개체의 CurrentByteOffsetI/O가 수행됩니다.

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

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

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

[in] Length

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

[out] Buffer

파일에서 읽은 데이터를 수신하는 호출자 할당 버퍼에 대한 포인터입니다.

[in] Flags

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

기	의미
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	미니 필터 드라이버는 이 플래그를 설정하여 FltReadFile 파일 개체의 CurrentByteOffset 필드를 업데이트하지 않도록 지정할 수 있습니다.
FLTFL_IO_OPERATION_NON_CACHED	미니 필터 드라이버는 파일 개체가 FILE_NO_INTERMEDIATE_BUFFERING 함께 열리지 않은 경우에도 캐시되지 않은 읽기를 지정하도록 이 플래그를 설정할 수 있습니다.
FLTFL_IO_OPERATION_PAGING	미니 필터 드라이버는 페이징 읽기를 지정하도록 이 플래그를 설정할 수 있습니다.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	미니 필터 드라이버는 이 플래그를 설정하여 동기 페이징 I/O 읽기를 지정할 수 있습니다. 이 플래그를 설정하는 미니 필터 드라이버도 FLTFL_IO_OPERATION_PAGING 플래그를 설정해야 합니다. Windows Vista부터 사용할 수 있습니다.

[out, optional] BytesRead

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

[in, optional] CallbackRoutine

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

[in, optional] CallbackContext

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

반환 값

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

발언

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

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

FltReadFile 다음 중 하나가 true이면 캐시되지 않은 I/O를 수행합니다.

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

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

Buffer 매개 변수가 가리키는 버퍼는 기본 스토리지 디바이스의 맞춤 요구 사항에 따라 정렬되어야 합니다. 이러한 정렬된 버퍼를 할당하려면 FltAllocatePoolAlignedWithTag호출합니다.
ByteOffset 매개 변수가 가리키는 바이트 오프셋은 볼륨 섹터 크기의 음수가 아닌 배수여야 합니다.
Length 매개 변수에 지정된 길이는 볼륨 섹터 크기의 음수가 아닌 배수여야 합니다.

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

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

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

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