Функция 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, приложение должно соответствовать некоторым требованиям:

Если часть файла, определенного  параметром 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, CreateFileFileIOCompletionRoutine,  MsgWaitForMultipleObjectsEx, OVERLAPPED,   ReadFileSetErrorMode, 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

-

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz