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

Статья
10/04/2023

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

Синтаксис

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

Параметры

[in] FileObject

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

[in] FileOffset

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

[in] Length

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

[in] Wait

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

[in] LockKey

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

[in] Buffer

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

[out] IoStatus

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

[in] DeviceObject

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

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

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

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

Вместо реализации процедуры быстрой записи ввода-вывода для конкретной файловой системы разработчикам файловых систем, поддерживающих кэширование файлов, следует рассмотреть возможность использования FsRtlCopyWrite в качестве точки входа файловой системы для обработки запросов на запись быстрых операций ввода-вывода. Для этого необходимо, чтобы подпрограмма DriverEntry файловой системы установила точку входа FastIoWrite fsRtlCopyWrite в структуре 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, функция FsRtlCopyWrite гарантированно скопирует данные и возвращает значение TRUE. Если необходимые страницы кэшированного файла уже находятся в памяти, данные будут скопированы немедленно и блокировка не возникнет. Если какие-либо необходимые страницы не являются резидентами, вызывающий объект будет переведен в состояние ожидания, пока все необходимые страницы не будут резидентами, и данные можно будет скопировать.

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

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

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

Требования

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

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

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite

Поделиться через