FltWriteFile 함수(fltkernel.h)

아티클
02/29/2024

FltWriteFile 은 열려 있는 파일, 스트림 또는 디바이스에 데이터를 쓰는 데 사용됩니다.

구문

NTSTATUS FLTAPI FltWriteFile(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext
);

매개 변수

[in] InitiatingInstance

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

[in] FileObject

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

[in, optional] ByteOffset

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

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

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

ByteOffset이 지정되지 않은 경우:

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

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

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

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

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

Windows 8 전에는 이 매개 변수에 대해 특수 상수 FILE_WRITE_TO_END_OF_FILE 및 FILE_USE_FILE_POINTER_POSITION 지원되지 않습니다.

[in] Length

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

[in] Buffer

파일에 쓸 데이터가 포함된 버퍼에 대한 포인터입니다. 캐시되지 않은 I/O에 대해 파일을 여는 경우 기본 스토리지 디바이스의 맞춤 요구 사항에 따라 이 버퍼를 정렬해야 합니다. 미니필터 드라이버는 FltAllocatePoolAlignedWithTag를 호출하여 이러한 정렬된 버퍼를 할당할 수 있습니다.

[in] Flags

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

플래그	의미
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	미니필터 드라이버는 FltWriteFile 이 파일 개체의 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] BytesWritten

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

[in, optional] CallbackRoutine

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

[in, optional] CallbackContext

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

반환 값

FltWriteFile 은 파일 시스템에서 반환한 NTSTATUS 값을 반환합니다.

설명

미니필터 드라이버는 FltWriteFile 을 호출하여 열려 있는 파일에 데이터를 씁니다.

FltWriteFile을 사용하면 쓰기 요청이 시작 instance 아래에 연결된 미니필터 드라이버 인스턴스 및 파일 시스템으로 전송됩니다. 지정된 instance 위에 연결된 인스턴스는 쓰기 요청을 받지 않습니다.

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

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

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

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

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

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

여러 스레드가 동일한 파일 개체에 대해 FltWriteFile 을 호출하고 동기 I/O를 위해 파일 개체를 연 경우 Filter Manager는 파일에서 I/O를 직렬화하지 않습니다. 이와 관련하여 FltWriteFile 은 ZwWriteFile과 다릅니다.