Функция ZwReadFile (wdm.h)

Статья
03/08/2023

Подпрограмма ZwReadFile считывает данные из открытого файла.

Синтаксис

NTSYSAPI NTSTATUS ZwReadFile(
  [in]           HANDLE           FileHandle,
  [in, optional] HANDLE           Event,
  [in, optional] PIO_APC_ROUTINE  ApcRoutine,
  [in, optional] PVOID            ApcContext,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [out]          PVOID            Buffer,
  [in]           ULONG            Length,
  [in, optional] PLARGE_INTEGER   ByteOffset,
  [in, optional] PULONG           Key
);

Параметры

[in] FileHandle

Дескриптор объекта файла. Этот дескриптор создается путем успешного вызова ZwCreateFile или ZwOpenFile.

[in, optional] Event

При необходимости можно использовать дескриптор объекта события для установки в состояние сигнала после завершения операции чтения. Драйверы устройства и промежуточные драйверы должны задать для этого параметра значение NULL.

[in, optional] ApcRoutine

Этот параметр зарезервирован. Драйверы устройств и промежуточных водителей должны задавать для этого указателя значение NULL.

[in, optional] ApcContext

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции чтения. Элемент Information получает количество байтов, фактически считанных из файла.

[out] Buffer

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

[in] Length

Размер (в байтах) буфера, на который указывает buffer.

[in, optional] ByteOffset

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

Если вызов ZwCreateFile задает один из флагов CreateOptions FILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT, диспетчер ввода-вывода сохраняет текущую позицию файла. Если это так, вызывающий объект ZwReadFile может указать, что вместо явного значения ByteOffset используется смещение текущей позиции файла. Эту спецификацию можно сделать с помощью одного из следующих методов:

Укажите указатель на LARGE_INTEGER значение с элементом HighPart , равным -1, а для элемента LowPart — системное значение FILE_USE_FILE_POINTER_POSITION.
Передайте указатель NULL для ByteOffset.

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

Даже если диспетчер ввода-вывода сохраняет текущую позицию файла, вызывающий объект может сбросить эту позицию, передав явное значение ByteOffsetв ZwReadFile. Это автоматически изменяет текущую позицию файла на это значение ByteOffset , выполняет операцию чтения, а затем обновляет позицию в соответствии с количеством фактически прочитанных байтов. Этот метод предоставляет вызывающей объекту атомарную службу поиска и чтения.

[in, optional] Key

Драйверы устройств и промежуточных водителей должны задавать для этого указателя значение NULL.

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

ZwReadFile возвращает либо STATUS_SUCCESS, либо соответствующий код ошибки NTSTATUS.

Если в предыдущем вызове ZwCreateFile для флага FILE_NO_INTERMEDIATE_BUFFERING в параметре CreateOptions задано значение ZwCreateFile, параметры Length и ByteOffsetзначения ZwReadFile должны быть кратными размеру сектора. Дополнительные сведения см. в разделе ZwCreateFile.

ZwReadFile начинает чтение из заданного byteOffset или текущей позиции файла в заданный буфер. Операция чтения завершается при одном из следующих условий:

Буфер заполнен, так как число байтов, указанное параметром Length , было считано. Таким образом, данные больше не могут быть помещены в буфер без переполнения.
Конец файла достигается во время операции чтения, поэтому в файле больше нет данных для передачи в буфер.

Если вызывающий объект открыл файл с флагом SYNCHRONIZE, установленным в DesiredAccess, вызывающий поток может синхронизироваться с завершением операции чтения, ожидая дескриптора файла FileHandle. Дескриптор получает сигнал при каждом завершении операции ввода-вывода, выполненной для дескриптора. Однако вызывающий объект не должен ждать дескриптора, который был открыт для синхронного доступа к файлам (FILE_SYNCHRONOUS_IO_NONALERT или FILE_SYNCHRONOUS_IO_ALERT). В этом случае ZwReadFile ожидает от имени вызывающего объекта и не возвращается до завершения операции чтения. Вызывающий объект может безопасно ждать дескриптора файла, только если выполняются все три из следующих условий:

Дескриптор был открыт для асинхронного доступа (то есть не указан флаг FILE_SYNCHRONOUS_IO_XXX ).
Дескриптор используется только для одной операции ввода-вывода за раз.
ZwReadFile вернул STATUS_PENDING.

Драйвер должен вызывать ZwReadFile в контексте системного процесса, если существует одно из следующих условий:

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

Дескрипторы файлов и событий допустимы только в контексте процесса, в котором создаются дескрипторы. Поэтому, чтобы избежать брешей в системе безопасности, драйвер должен создать любой файл или дескриптор события, который он передает в ZwReadFile в контексте системного процесса, а не в контексте процесса, в который находится драйвер.

Аналогичным образом , ZwReadFile должен вызываться в контексте системного процесса, если он уведомляет драйвер о завершении ввода-вывода с помощью APC, так как APC всегда активируются в контексте потока, который выдает запрос ввода-вывода. Если драйвер вызывает ZwReadFile в контексте процесса, отличного от системного, APC может быть отложен на неопределенный срок или вообще не срабатывает.

Дополнительные сведения о работе с файлами см. в разделе Использование файлов в драйвере.

Вызывающие файлы ZwReadFile должны выполняться в среде IRQL = PASSIVE_LEVEL и с включенными специальными ППК ядра.

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя "NtReadFile" вместо "ZwReadFile".

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

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

KeInitializeEvent

ZwCreateFile

ZwQueryInformationFile

ZwSetInformationFile

ZwWriteFile