Функция ReadFileEx (fileapi.h)

Статья
08/23/2023

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

Для синхронного чтения данных из файла или устройства используйте функцию ReadFile .

Синтаксис

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Параметры

[in] hFile

Дескриптор для файла или устройства ввода-вывода (например, файловый поток, физический диск, том, буфер консоли, ленточный накопитель, сокет, ресурс связи, почтовый слоот или канал).

Это может быть любой дескриптор, открытый с флагом FILE_FLAG_OVERLAPPED функцией CreateFile , или дескриптор сокета, возвращенный функцией сокета или приемом .

Этот дескриптор также должен иметь право доступа к GENERIC_READ . Дополнительные сведения о правах доступа см. в разделе Безопасность файлов и права доступа.

[out, optional] lpBuffer

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

Этот буфер должен оставаться действительным в течение операции чтения. Приложение не должно использовать этот буфер до завершения операции чтения.

[in] nNumberOfBytesToRead

Количество байтов, чтение которых необходимо выполнить.

[in, out] lpOverlapped

Указатель на структуру данных OVERLAPPED , которая предоставляет данные для использования во время асинхронной (перекрывающейся) операции чтения файла.

Для файлов, поддерживающих смещение байтов, необходимо указать смещение байтов, с которого следует начать чтение из файла. Это смещение можно указать, задав элементы Offset и OffsetHigh структуры OVERLAPPED . Для файлов или устройств, которые не поддерживают смещения байтов, offset и OffsetHigh игнорируются.

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

Функция ReadFileEx использует элементы Internal и InternalHigh структуры OVERLAPPED. Приложение не должно задавать эти элементы.

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

[in] lpCompletionRoutine

Указатель на подпрограмму завершения, вызываемую при завершении операции чтения и состоянии ожидания вызывающего потока. Дополнительные сведения о процедуре завершения см. в разделе FileIOCompletionRoutine.

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

Если функция выполняется успешно, возвращается ненулевое значение.

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

Если функция выполняется успешно, вызывающий поток ожидает асинхронную операцию ввода-вывода: перекрываемую операцию чтения из файла. Когда эта операция ввода-вывода завершается и вызывающий поток блокируется в состоянии ожидания с оповещениями, система вызывает функцию, на которую указывает lpCompletionRoutine, и состояние ожидания завершается с кодом возврата WAIT_IO_COMPLETION.

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

Если ReadFileEx пытается прочитать данные после завершения файла (EOF), вызов Метода GetOverlappedResult для этой операции возвращает значение FALSE , а GetLastError — ERROR_HANDLE_EOF.

При использовании ReadFileEx следует проверка GetLastError, даже если функция возвращает значение "success" в проверка для условий, которые являются "успешными", но имеют некоторые результаты, о которых вы можете знать. Например, переполнение буфера при вызове ReadFileEx возвращает значение TRUE, а GetLastError сообщит о переполнении с ERROR_MORE_DATA. Если вызов функции выполнен успешно и условия предупреждения отсутствуют, GetLastError вернет ERROR_SUCCESS.

Функция ReadFileEx может завершиться ошибкой, если имеется слишком много невыполненных асинхронных запросов ввода-вывода. В случае такого сбоя GetLastError может вернуть ERROR_INVALID_USER_BUFFER или ERROR_NOT_ENOUGH_MEMORY.

Чтобы отменить все ожидающие асинхронные операции ввода-вывода, используйте один из следующих вариантов:

CancelIo — эта функция отменяет только операции, выданные вызывающим потоком для указанного дескриптора файла.
CancelIoEx — эта функция отменяет все операции, выданные потоками для указанного дескриптора файла.

Используйте CancelSynchronousIo для отмены ожидающих синхронных операций ввода-вывода.

Операции ввода-вывода, отмененные с ошибкой ERROR_OPERATION_ABORTED.

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

При попытке чтения данных из почтового слота, буфер которого слишком мал, ReadFileEx возвращает значение FALSE, а GetLastError — ERROR_INSUFFICIENT_BUFFER.

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

Приложение использует функции MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx и SleepEx для ввода состояния ожидания с оповещениями. Дополнительные сведения о предупреждаемых ожиданиях и перекрывающихся входных и выходных данных см. в разделе Сведения о синхронизации.

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

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Транзакция операций

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

Примеры

Пример см. в разделе Сервер именованных каналов с использованием процедур завершения.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll