Функция ReadFileEx

Функция ReadFileEx читает данные из файла асинхронно. Она предназначена исключительно для асинхронных операций, в отличие от функции ReadFile, которая предназначена и для синхронных, и для асинхронных операций. ReadFileEx позволяет приложению в ходе операции чтения файла исполнять другую работу.

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

Синтаксис

BOOL ReadFileEx(
  HANDLE hFile,                        // дескриптор файла
  LPVOID lpBuffer,                     // буфер данных
  DWORD nNumberOfBytesToRead,          // число читаемых байтов
  LPOVERLAPPED lpOverlapped,           // смещение
  LPOVERLAPPED_COMPLETION_ROUTINE 
        lpCompletionRoutine            // процедура завершения
);

Параметры

hFile

[in] Дескриптор файла, который читается. Дескриптор файла должен быть, создан с флажком FILE_FLAG_OVERLAPPED и должен иметь право доступа GENERIC_READ. Подробную информацию см. в статье Защита файла и права доступа.

Windows NT/2000/XP: Этот параметр hFile может быть любым дескриптором открытым с флажком FILE_FLAG_OVERLAPPED функцией CreateFile или дескриптором сокета, возвращенным функцией socket или функцией accept.

Windows 95/98/Me: Этот параметр hFile может быть коммуникационным ресурсом, открытым с флажком FILE_FLAG_OVERLAPPED функцией CreateFile или дескриптором сокета, возвращенным при помощи функций socket или accept. Вы не можете выполнять асинхронные операции чтения в почтовом ящике в ядре Windows, в именованных каналах или в файлах на диске.

lpBuffer

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

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

nNumberOfBytesToRead

[in] Число байтов, которые читаются из файла.

lpOverlapped

[in] Указатель на структуру данных OVERLAPPED, которая снабжает данными, используемыми в ходе асинхронной (overlapped) операции чтения из файла

Если файл, заданный параметром hFile поддерживает концепцию смещения байтов, программа вызывающая функцию ReadFileEx должна установить смещение байта, в пределах файла, с которого должно начаться чтение . Вызывающая программа определяет смещение байта, устанавливая его в членах Offset и OffsetHigh структуры OVERLAPPED.

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

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

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

lpCompletionRoutine

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

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

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

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

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

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

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

Замечания

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

Когда работа с файлами открывается с флажком FILE_FLAG_NO_BUFFERING, приложение должно соответствовать некоторым требованиям:

Доступ к файлу должен начаться при смещениях байтов в пределах файла, которые должны быть целыми числами кратными размеру сектора тома. Чтобы выяснить размер сектора тома, вызовите функцию GetDiskFreeSpace.
Доступ к файлу должен быть числом байтов, которое является целым числом кратным размеру сектора тома. Например, если размер сектора - 512 байтов, приложение может запросить для чтения и записи 512, 1024 или 2048 байтов, но не 335, 981 или 7171 байт.
Адреса буферов для операций чтения и записи должны выравниваться кратно сектору (выравниваются адреса в памяти, которые являются целыми числами, кратными размеру сектора тома). Один из способов выравнивания буфера кратно сектору, является использование функции VirtualAlloc, которая назначает буфера. Эта функция выделяет память, выравнивая их по адресам, которые являются целыми числами, кратными размеру страницы памяти системы. Поскольку размеры и страницы памяти, и сектора тома являются степенью 2, память, выровненная кратно размеру страницы памяти системы также выравнивается кратно и размеру сектора тома.

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

Если ReadFileEx пытается читать данные из почтового слота в ядре Windows, буфер которого является слишком маленьким, функция возвращает значение ЛОЖЬ (FALSE), а GetLastError возвращает ошибку ERROR_INSUFFICIENT_BUFFER.

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

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

Чтобы отменить все ждущие обработки асинхронные операции ввода-вывода (I/O), используйте функцию CancelIo. Эта функция отменяет только операции, порождаемые вызывающим потоком, для заданного дескриптора файла. Отмененные операции ввода-вывода (I/O) завершаются ошибкой ERROR_OPERATION_ABORTED.

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

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

Windows 95/98/Me: На этой платформе, для обмена данными ни ReadFileEx, ни WriteFileEx портами коммуникации использоваться не могут. Однако, чтобы исполнять асинхронную коммуникацию, Вы можете использовать функции ReadFile и WriteFile.

Код примера

Пример смотри в статье Использование процедур завершения сервером именованного канала.

Смотри также

Обзор Управление файлами, Функции для файлового ввода-вывода (I/O), CancelIo, CreateFile, FileIOCompletionRoutine, MsgWaitForMultipleObjectsEx, OVERLAPPED, ReadFile, SetErrorMode, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx

Размещение и совместимость ReadFileEx
К	Windows XP	Да
л	Windows 2000 Professional	Да
и	Windows NT Workstation	Да
е	Windows Me	Да
н	Windows 98	Да
т	Windows 95	Да

С	Windows Server 2003	Да
е	Windows 2000 Server	Да
р	Windows NT Server	Да
в
е
р
Используемая библиотека		Kernel32.lib
Используемая DLL		-
Заголовочный файл
- объявлено в		Winbase.h
- включено в		Windows.h
Unicode		-
Замечания по платформе		Не имеется

Назад в оглавление

На главную страницу

На оглавление справки