FltReadFile 함수(fltkernel.h)

아티클
11/16/2023

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

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

[in] FileObject

데이터를 읽을 파일의 FILE_OBJECT 대한 포인터입니다. 이 파일 개체는 현재 열려 있어야 합니다. 파일 개체가 아직 열려 있지 않거나 더 이상 열려 있지 않을 때(예: 사전 만들기 또는 정리 후 콜백 루틴에서) FltReadFile 을 호출하면 시스템이 확인된 빌드에서 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가 반환되면 복원합니다. FltReadFile 호출자(및 더 높은 고도의 필터)의 관점에서 CurrrentByteOffset은 업데이트되지 않습니다. 그러나 호출자 아래의 필터는 읽기/쓰기 후 콜백에서 업데이트된 CurrentByteOffset 값을 확인합니다.

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

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

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를 직렬화하려고 시도하지 않습니다. 이와 관련하여 FltReadFile 은 ZwReadFile과 다릅니다.