CcPrepareMdlWrite routine

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

FileObject [in]

Pointer to a file object for the cached file.

FileOffset [in]

Pointer to a variable that specifies the starting byte offset within the cached file where the data is to be written.

Length [in]

Length in bytes of the data to be written to the system cache.

MdlChain [out]

A chain of one or more memory descriptor lists (MDL) describing the pages to which the data is to be written.

IoStatus [out]

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

Target platform

Universal

Header

Ntifs.h (include Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

< DISPATCH_LEVEL

See also

CcCopyWrite
CcInitializeCacheMap
CcMdlWriteAbort
CcMdlWriteComplete
IoAllocateMdl
IoBuildPartialMdl
MmGetMdlByteCount
MmGetMdlByteOffset
MmGetMdlPfnArray
MmGetMdlVirtualAddress
MmGetSystemAddressForMdl
MmGetSystemAddressForMdlSafe
MmInitializeMdl
MmMapLockedPages
MmPrepareMdlForReuse
MmProbeAndLockPages
MmUnlockPages
MmUnmapLockedPages

 

 

Send comments about this topic to Microsoft

Show: