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

Статья
09/27/2023

Подпрограмма FsRtlCopyRead копирует данные из кэшированного файла в пользовательский буфер.

Синтаксис

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

Параметры

[in] FileObject

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

[in] FileOffset

Начальная смещение байтов в кэшированном файле.

[in] Length

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

[in] Wait

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

[in] LockKey

Значение , связанное с диапазоном байтов для блокировки. Если диапазон для блокировки перекрывает другой диапазон, который уже заблокирован с неисключительной блокировкой, или если диапазон для чтения является поддиампом другого диапазона, который уже заблокирован неисключительно, значение в этом параметре должно быть ключом для этой неисключительной блокировки. Блокировка должна быть удержана родительским процессом вызывающего потока. В противном случае этот параметр не оказывает никакого влияния.

[out] Buffer

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

[out] IoStatus

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

[in] DeviceObject

Объект устройства для устройства, на котором хранятся файловые данные.

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

FsRtlCopyRead возвращает значение TRUE, если запрос на копирование был завершен, в противном случае — FALSE. Обратите внимание, что возвращаемое значение TRUE не обязательно означает, что операция копирования была успешной.

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

Вместо реализации процедуры быстрого чтения операций ввода-вывода для конкретной файловой системы разработчикам файловых систем, поддерживающих кэширование файлов, следует рассмотреть возможность использования FsRtlCopyRead в качестве точки входа файловой системы для обработки запросов на чтение быстрых операций ввода-вывода. Для этого необходимо, чтобы подпрограмма DriverEntry файловой системы установила точку входа FastIoReadзначение FsRtlCopyRead в структуре FAST_IO_DISPATCH объекта драйвера файловой системы. Кроме того, файловая система должна выполнять следующие действия.

Для каждого файла, в котором может выполняться быстрый ввод-вывод, файловая система должна выделить и инициализировать структуру FSRTL_COMMON_FCB_HEADER.

В большинстве файловых систем это достигается путем включения структуры FSRTL_COMMON_FCB_HEADER в блок управления файлами (FCB) или сопоставимую структуру, которая используется для поддержания состояния открытого файла.

Хранилище для структуры FSRTL_COMMON_FCB_HEADER обычно выделяется из страничного пула.
Для каждого файла, в котором может выполняться быстрый ввод-вывод, файловая система должна связать все файловые объекты с FSRTL_COMMON_FCB_HEADER структурой. Это делается путем задания элемента FsContext каждого файлового объекта таким образом, чтобы он указывал на эту структуру (или fcb или другую структуру, содержащую структуру FSRTL_COMMON_FCB_HEADER).
При кэшировании файла файловая система должна задать для члена IsFastIoPossible FSRTL_COMMON_FCB_HEADER структуры файла соответствующее значение. Это значение следует обновлять по мере необходимости до тех пор, пока файл остается кэшированным.

В частности, файловые системы должны устанавливать для члена IsFastIoPossible структуры FSRTL_COMMON_FCB_HEADER значение FastIoIsQuestionable , как только будет создана любая монопольная блокировка диапазона байтов в кэшированном файле.

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

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

Подпрограмма FastIoCheckIfPossible файловой системы отвечает за то, чтобы диапазон байтов, определенный fileOffset и Length , не включал только заблокированный диапазон байтов, для которого вызывающий объект не передает соответствующее значение LockKey . Если файловая система использует подпрограммы поддержки FsRtlXxxLockYyy для управления блокировками диапазона байтов, это можно сделать, вызвав FsRtlFastCheckLockForRead из подпрограммы FastIoCheckIfPossible перед вызовом FsRtlCopyRead.

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	PowerIrpDDis(wdm)

См. также раздел

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead

Share via