CcCopyReadEx function (ntifs.h)

Article
07/06/2023

The CcCopyReadEx routine copies data from a cached file to a user buffer. The I/O byte count for the operation is charged to the issuing thread.

Syntax

BOOLEAN CcCopyReadEx(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PETHREAD         IoIssuerThread
);

Parameters

[in] FileObject

A pointer to a file object for the cached file from which the data is to be read.

[in] FileOffset

A pointer to a variable that specifies the starting byte offset within the cached file.

[in] Length

The length in bytes of the data to be read.

[in] Wait

Set to TRUE if the caller can be put into a wait state until all the data has been copied, FALSE otherwise.

[out] Buffer

A pointer to a buffer into which the data is to be copied.

[out] IoStatus

A pointer to a caller-allocated structure that receives the final completion status and information about the operation. If not all of the data is copied successfully, IoStatus.Information contains the actual number of bytes that were copied.

[in] IoIssuerThread

The thread issuing the read request. For a file system with disk I/O accounting enabled, this is the thread the I/O is charged to. If IoIssuerThread is NULL, the I/O is charged to the current thread.

Return value

The CcCopyReadEx routine returns TRUE if the data was copied successfully, FALSE otherwise.

Remarks

If Wait is TRUE, CcCopyReadEx is guaranteed to complete the copy request and return TRUE. If the required pages of the cached file are already resident in memory, the data will be copied immediately and no blocking will occur. If any needed pages are not resident, the caller will be put in a wait state until all required pages have been made resident and the data can be copied.

If Wait is FALSE, CcCopyReadEx will refuse to block, and will return FALSE, if the required pages of the cached file are not already resident in memory.

FileOffset plus Length must be less than or equal to the size of the cached file, or an assertion failure will occur.

If any failure occurs, CcCopyReadEx raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcCopyReadEx raises an exception with the STATUS_INSUFFICIENT_RESOURCES status; if an I/O error occurs, CcCopyReadEx raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcCopyReadEx in a try-except or try-finally statement.

To cache a file, use CcInitializeCacheMap.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Target Platform	Universal
Header	ntifs.h (include Ntifs.h, FltKernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL