FltReadFile 함수(fltkernel.h)

아티클
02/06/2022
읽는 데 8분 걸림

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

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

[in, optional] ByteOffset

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

이 오프셋이 제공되거나 flags 매개 변수 에 FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET 플래그가 지정된 경우 FltReadFile 은 파일 개체의 CurrentByteOffset 필드를 업데이트하지 않습니다.

FileObject가 가리키는 파일 개체가 동기 I/O용으로 열린 경우 FltReadFile의 호출자는 이 매개 변수를 NULL로 설정하여 명시적 ByteOffset 값 대신 현재 파일 위치 오프셋을 사용하도록 지정할 수 있습니다. 현재 파일 위치를 사용하는 경우 FltReadFile 은 읽기 작업을 완료할 때 읽은 바이트 수를 추가하여 파일 개체의 CurrentByteOffset 필드를 업데이트합니다.

FileObject가 가리키는 파일 개체가 비동기 I/O에 대해 열린 경우 이 매개 변수가 필요하며 NULL일 수 없습니다.

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

다음 중 하나가 true인 경우 FltReadFile은 캐시되지 않은 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과 다릅니다.