Функция ZwReadFile (wdm.h)
Подпрограмма 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
Этот параметр зарезервирован. Драйверы устройств и промежуточных водителей должны задавать для этого указателя значение NULL.
[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.
Комментарии
Вызывающие ZwReadFile должны уже вызывать ZwCreateFile со значением FILE_READ_DATA или GENERIC_READ, заданным в параметре DesiredAccess .
Если в предыдущем вызове 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) |