CcPrepareMdlWrite function (ntifs.h)
The CcPrepareMdlWrite routine provides direct access to cached file memory so that the caller can write data to the file.
Syntax
void CcPrepareMdlWrite(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[out] PMDL *MdlChain,
[out] PIO_STATUS_BLOCK IoStatus
);
Parameters
[in] FileObject
Pointer to a file object for the cached file.
[in] FileOffset
Pointer to a variable that specifies the starting byte offset within the cached file where the data is to be written.
[in] Length
Length in bytes of the data to be written to the system cache.
[out] MdlChain
A chain of one or more memory descriptor lists (MDL) describing the pages to which the data is to be written.
[out] IoStatus
Pointer to an IO_STATUS_BLOCK structure. If the call to CcPrepareMdlWrite succeeds, IoStatus.Status is set to STATUS_SUCCESS. Otherwise, it is set to an appropriate NTSTATUS error code. IoStatus.Information is set to the actual number of bytes that were successfully locked down in the MDL chain.
Return value
None
Remarks
CcPrepareMdlWrite is similar to CcCopyWrite, except that the data is not copied to the cached file. Instead, the physical pages to be overwritten in the system cache are locked in memory, and CcPrepareMdlWrite returns one or more memory descriptor lists (MDL) describing the specified byte range. These pages remain locked in memory until CcMdlWriteComplete or CcMdlWriteAbort is called. Thus each call to CcPrepareMdlWrite must be followed by a call to CcMdlWriteComplete or CcMdlWriteAbort.
Note that the pages described by the MDL are locked in memory, but not mapped in system space. The caller can perform this mapping by calling MmGetSystemAddressForMdlSafe.
Note that even if the call to CcPrepareMdlWrite fails, one or more MDLs may have been allocated. The caller can examine the value of IoStatus.Information to determine whether this has occurred. If it has, the caller must call CcMdlWriteComplete to free the allocated MDLs.
If any failure occurs, CcPrepareMdlWrite raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcPrepareMdlWrite raises a STATUS_INSUFFICIENT_RESOURCES exception; if an I/O error occurs, CcPrepareMdlWrite raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcPrepareMdlWrite in a try-except or try-finally statement.
To cache a file, use CcInitializeCacheMap.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL |