CcMdlRead routine
The CcMdlRead routine provides direct access to cached file memory so that the caller can read data from the file.
Syntax
VOID CcMdlRead(
_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 desired data resides.Length [in]
Length in bytes of the data to be read from the system cache.MdlChain [out]
A chain of one or more memory descriptor lists (MDL) describing the pages containing the data.IoStatus [out]
Pointer to an IO_STATUS_BLOCK structure. If the call to CcMdlRead 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
CcMdlRead is similar to CcCopyRead, except that the cached file data is not copied. Instead, the physical pages containing the data are locked in memory, and CcMdlRead returns one or more memory descriptor lists (MDL) describing the specified byte range. The pages containing the data remain locked in memory until CcMdlReadComplete is called. Thus each call to CcMdlRead must be followed by a call to CcMdlReadComplete.
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.
If any failure occurs, CcMdlRead raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcMdlRead raises a STATUS_INSUFFICIENT_RESOURCES exception; if an I/O error occurs, CcMdlRead raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcMdlRead in a try-except or try-finally statement.
Note that even if the call to CcMdlRead 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 CcMdlReadComplete to free the allocated MDLs.
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