Функция CcCopyReadEx (ntifs.h)

Статья
07/11/2023

Подпрограмма CcCopyReadEx копирует данные из кэшированного файла в пользовательский буфер. Количество байтов ввода-вывода для операции взимается с выдающего потока.

Синтаксис

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
);

Параметры

[in] FileObject

Указатель на объект файла для кэшированного файла, из которого считываются данные.

[in] FileOffset

Указатель на переменную, указывающую смещение начального байта в кэшированном файле.

[in] Length

Длина считываемых данных в байтах.

[in] Wait

Задайте значение TRUE, если вызывающий объект может быть переведен в состояние ожидания, пока не будут скопированы все данные. В противном случае — FALSE.

[out] Buffer

Указатель на буфер, в который копируются данные.

[out] IoStatus

Указатель на структуру, выделенную вызывающим объектом, которая получает состояние завершения и сведения об операции. Если не все данные успешно скопированы, IoStatus.Information содержит фактическое количество скопированных байтов.

[in] IoIssuerThread

Поток, выдающий запрос на чтение. Для файловой системы с включенным учетом дискового ввода-вывода это поток, за который взимается плата за ввод-вывод. Если ioIssuerThread имеет значение NULL, операции ввода-вывода оплачиваются в текущем потоке.

Возвращаемое значение

Подпрограмма CcCopyReadEx возвращает значение TRUE, если данные были успешно скопированы, в противном случае — FALSE.

Если параметр Wait имеет значение TRUE, CcCopyReadEx гарантированно завершит запрос на копирование и возвратит значение TRUE. Если необходимые страницы кэшированного файла уже находятся в памяти, данные будут скопированы немедленно и блокировка не возникнет. Если какие-либо необходимые страницы не являются резидентами, вызывающий объект будет помещен в состояние ожидания, пока все необходимые страницы не станут резидентами, и данные можно будет скопировать.

Если параметр Wait имеет значение FALSE, CcCopyReadEx откажется блокировать и возвращает значение FALSE, если необходимые страницы кэшированного файла еще не находятся в памяти.

Значение FileOffset и Length должно быть меньше или равно размеру кэшированного файла, иначе произойдет сбой утверждения.

При возникновении какого-либо сбоя CcCopyReadEx создает исключение состояния для этого конкретного сбоя. Например, если происходит сбой выделения пула, CcCopyReadEx вызывает исключение с состоянием STATUS_INSUFFICIENT_RESOURCES ; При возникновении ошибки ввода-вывода CcCopyReadEx вызывает исключение состояния ошибки ввода-вывода. Таким образом, чтобы получить контроль в случае сбоя, драйвер должен заключить вызов CcCopyReadEx в оператор try-except или try-finally .

Чтобы кэшировать файл, используйте CcInitializeCacheMap.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h, FltKernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL