FltWriteFileEx function (fltkernel.h)

FltWriteFileEx is used to write data to an open file, stream, or device. This function extends FltWriteFile to allow the optional use of an MDL for write data instead of a mapped buffer address.

Syntax

NTSTATUS FLTAPI FltWriteFileEx(
  [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, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

Parameters

[in] InitiatingInstance

An opaque instance pointer for the minifilter driver instance that the operation is to be sent to. The instance must be attached to the volume where the file resides. This parameter is required and cannot be NULL.

[in] FileObject

A pointer to a FILE_OBJECT for the file that the data is to be written to. This file object must be currently open. Calling FltWriteFileEx 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.

[in, optional] ByteOffset

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

If ByteOffset is specified, the I/O is performed at that offset, regardless of the current value of the file object’s CurrentByteOffset field.

• If the file was opened for synchronous I/O (FO_SYNCHRONOUS_IO is set in the file object’s Flags field), the caller can set ByteOffset->LowPart to FILE_USE_FILE_POINTER_POSITION and ByteOffset->HighPart to -1 to have the I/O performed at the file object’s CurrentByteOffset field. If the file wasn't opened for synchronous I/O, using FILE_USE_FILE_POINTER_POSITION is an error.
• The caller can set ByteOffset->LowPart to FILE_WRITE_TO_END_OF_FILE and ByteOffset->HighPart to -1 to start the write at the end of the file (i.e., perform an appending write).

If ByteOffset isn't specified:

• If the file wasn't opened for synchronous I/O, that's an error.
• Otherwise, the I/O is performed at the file object’s CurrentByteOffset.

If the file object was opened for synchronous I/O, the CurrentByteOffset field gets updated unless the caller passes the FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET flag.

• Note: the file system still updates CurrentByteOffset in this case. Filter Manager saves the CurrentByteOffset value before sending the I/O down the stack and restores it when the I/O returns. From the perspective of the caller of FltWriteFileEx (and filters at higher altitudes) the CurrrentByteOffset isn't updated. But filters below the caller see the updated CurrentByteOffset value in their post-read/write callbacks.

If the file object wasn't opened for synchronous I/O, the CurrentByteOffset field isn't updated regardless of the state of the ByteOffset parameter.

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

FltWriteFileEx doesn't support the FILE_WRITE_TO_END_OF_FILE flag.

[in] Length

The size, in bytes, of the buffer that the Buffer parameter points to. If an MDL is provided in Mdl, then Length is the size of the data that MDL describes.

[in] Buffer

A 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.

If an MDL is provided in Mdl, Buffer must be NULL.

[in] Flags

A bitmask of flags that specify the type of write operation to be performed.

[out, optional] BytesWritten

A 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.

[in, optional] CallbackRoutine

A 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.

[in, optional] CallbackContext

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

[in, optional] Key

An optional key associated with a file object lock.

[in, optional] Mdl

An optional MDL that describes the data to write. If a buffer is provided in Buffer, then Mdl must be NULL.

Return value

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

Remarks

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

FltWriteFileEx 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.

FltWriteFileEx 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 FltWriteFileEx:

• 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, FltWriteFileEx 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 FltWriteFileEx 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, FltWriteFileEx differs from ZwWriteFile.

The Mdl parameter is provided as a convenience when a minifilter already has an MDL available. The MDL is used directly and the additional step of mapping an address for Buffer can be avoided.

Requirements

See also

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltReadFileEx

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile