Expand Minimize

FltWriteFile function

FltWriteFile is used to write data to an open file, stream, or device.

Syntax


NTSTATUS FltWriteFile(
  _In_       PFLT_INSTANCE InitiatingInstance,
  _In_       PFILE_OBJECT FileObject,
  _In_opt_   PLARGE_INTEGER ByteOffset,
  _In_       ULONG Length,
  _In_       PVOID Buffer,
  _In_       FLT_IO_OPERATION_FLAGS Flags,
  _Out_opt_  PULONG BytesWritten,
  _In_opt_   PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  _In_opt_   PVOID CallbackContext
);

Parameters

InitiatingInstance [in]

Opaque instance pointer for the minifilter driver instance that is initiating the write request. This parameter is required and cannot be NULL.

FileObject [in]

Pointer to a file object for the file that the data is to be written to. This file object must be currently open. Calling FltWriteFile when the file object is not yet open or is no longer open (for example, in a pre-create or post-cleanup callback routine) causes the system to ASSERT on a checked build. This parameter is required and cannot be NULL.

ByteOffset [in, optional]

Pointer to a caller-allocated variable that specifies the starting byte offset within the file where the write operation is to begin.

If this offset is supplied, or if the FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET flag is specified in the Flags parameter, FltWriteFile does not update the file object's CurrentByteOffset field.

If the file object that FileObject points to was opened for synchronous I/O, the caller of FltWriteFile can specify that the current file position offset be used instead of an explicit ByteOffset value by setting this parameter to NULL. If the current file position is used, FltWriteFile updates the file object's CurrentByteOffset field by adding the number of bytes written when it completes the write operation.

If the file object that FileObject points to was opened for asynchronous I/O, this parameter is required and cannot be NULL.

Note  Prior to Windows 8, the special constants FILE_WRITE_TO_END_OF_FILE and FILE_USE_FILE_POINTER_POSITION are not supported for this parameter.

Length [in]

Size, in bytes, of the buffer that the Buffer parameter points to.

Buffer [in]

Pointer to a buffer that contains the data to be written to the file. If the file is opened for noncached I/O, this buffer be must be aligned in accordance with the alignment requirement of the underlying storage device. Minifilter drivers can allocate such an aligned buffer by calling FltAllocatePoolAlignedWithTag.

Flags [in]

Bitmask of flags specifying the type of write operation to be performed.

FlagMeaning

FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET

Minifilter drivers can set this flag to specify that FltWriteFile should not update the file object's CurrentByteOffset field.

FLTFL_IO_OPERATION_NON_CACHED

Minifilter drivers can set this flag to specify a noncached write, even if the file object was not opened with FILE_NO_INTERMEDIATE_BUFFERING.

FLTFL_IO_OPERATION_PAGING

Minifilter drivers can set this flag to specify a paging write.

FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING

Minifilter drivers can set this flag to specify a synchronous paging I/O write. Minifilter drivers that set this flag must also set the FLTFL_IO_OPERATION_PAGING flag.

This flag is available for Windows Vista and later versions of the Windows operating system.

 

BytesWritten [out, optional]

Pointer to a caller-allocated variable that receives the number of bytes written to the file. If CallbackRoutine is not NULL, this parameter is ignored. Otherwise, this parameter is optional and can be NULL.

CallbackRoutine [in, optional]

Pointer to a PFLT_COMPLETED_ASYNC_IO_CALLBACK-typed callback routine to call when the write operation is complete. This parameter is optional and can be NULL.

CallbackContext [in, optional]

Context pointer to be passed to the CallbackRoutine if one is present. This parameter is optional and can be NULL. If CallbackRoutine is NULL, this parameter is ignored.

Return value

FltWriteFile returns the NTSTATUS value that was returned by the file system.

Remarks

A minifilter driver calls FltWriteFile to write data to an open file.

FltWriteFile causes a write request to be sent to the minifilter driver instances attached below the initiating instance and to the file system. The specified instance and the instances attached above it do not receive the write request.

FltWriteFile performs noncached I/O if either of the following is true:

  • The caller set the FLTFL_IO_OPERATION_NON_CACHED flag in the Flags parameter.

  • The file object was opened for noncached I/O. Usually, this is done by specifying the FILE_NO_INTERMEDIATE_BUFFERING CreateOptions flag in the preceding call to FltCreateFile, FltCreateFileEx, or ZwCreateFile.

Noncached I/O imposes the following restrictions on the parameter values passed to FltWriteFile:

  • The buffer that the Buffer parameter points to must be aligned in accordance with the alignment requirement of the underlying storage device. To allocate such an aligned buffer, call FltAllocatePoolAlignedWithTag.

  • The byte offset that the ByteOffset parameter points to must be a nonnegative multiple of the volume's sector size.

  • The length specified in the Length parameter must be a nonnegative multiple of the volume's sector size.

If the value of the CallbackRoutine parameter is not NULL, the write operation is performed asynchronously.

If the value of the CallbackRoutine parameter is NULL, the write operation is performed synchronously. That is, FltWriteFile waits until the write operation is complete before returning. This is true even if the file object that FileObject points to was opened for asynchronous I/O.

If multiple threads call FltWriteFile for the same file object, and the file object was opened for synchronous I/O, the Filter Manager does not attempt to serialize I/O on the file. In this respect, FltWriteFile differs from ZwWriteFile.

Requirements

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

PASSIVE_LEVEL

See also

FltAllocatePoolAlignedWithTag
FltCreateFile
FltCreateFileEx
FltReadFile
ObReferenceObjectByHandle
PFLT_COMPLETED_ASYNC_IO_CALLBACK
ZwReadFile
ZwWriteFile

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.