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

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

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

Синтаксис

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Параметры

[in] hFile

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

Необходимо создать параметр hFile с доступом на чтение. Дополнительные сведения см. в универсальных прав доступа и права на безопасность файлов и доступ.

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

[out] lpBuffer

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

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

[in] nNumberOfBytesToRead

Максимальное число байтов для чтения.

[out, optional] lpNumberOfBytesRead

Указатель на переменную, которая получает число байтов, считываемых при использовании синхронного параметра hFile. ReadFile задает это значение нулю перед выполнением любой проверки ошибок или работы. Используйте null для этого параметра, если это асинхронная операция, чтобы избежать потенциально ошибочных результатов.

Этот параметр может быть NULL только в том случае, если параметр lpOverlapped не NULL.

Windows 7: этот параметр нельзя NULL.

Дополнительные сведения см. в разделе "Примечания".

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED требуется, если был открыт параметр hFile hFile с FILE_FLAG_OVERLAPPED, в противном случае его можно NULL.

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

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

Дополнительные сведения о различных сочетаниях lpOverlapped и FILE_FLAG_OVERLAPPEDсм. в разделе "Примечания" и разделе синхронизации и положения файлов.

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

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

Если функция завершается сбоем или выполняется асинхронно, возвращаемое значение равно нулю (FALSE). Чтобы получить расширенные сведения об ошибке, вызовите функцию getLastError .

Замечания

Функция ReadFile возвращается при возникновении одного из следующих условий:

• Число запрошенных байтов считывается.
• Операция записи завершается в конце канала записи.
• Используется асинхронный дескриптор, и чтение происходит асинхронно.
• Возникает ошибка.

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

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

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

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

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

Функция readFile может завершиться ошибкой с ERROR_NOT_ENOUGH_QUOTA, что означает, что буфер вызывающего процесса не может быть заблокирован на странице. Дополнительные сведения см. в SetProcessWorkingSetSize.

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

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

Символы можно считывать из буфера входных данных консоли с помощью ReadFile с дескриптором для ввода в консоль. Режим консоли определяет точное поведение функции ReadFile. По умолчанию режим консоли ENABLE_LINE_INPUT, который указывает, что ReadFile следует читать, пока не достигнет возврата каретки. Если нажать клавиши CTRL+C, вызов завершается успешно, но GetLastError возвращает ERROR_OPERATION_ABORTED. Дополнительные сведения см. в разделе CreateFile.

При чтении с устройства связи поведение ReadFile определяется текущим временем ожидания связи, заданным и извлекаемым с помощью SetCommTimeouts и функций GetCommTimeouts. Непредсказуемые результаты могут возникнуть, если не удается задать значения времени ожидания. Дополнительные сведения о времени ожидания связи см. в COMMTIMEOUTS.

Если ReadFile пытается считывать из почтового объекта с слишком небольшим буфером, функция возвращает FALSE и GetLastError возвращает ERROR_INSUFFICIENT_BUFFER.

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

Если hFile был открыт с помощью FILE_FLAG_OVERLAPPED, в силу применяются следующие условия:

• Параметр lpOverlapped должен указывать на допустимую и уникальную структуру OVERLAPPED, в противном случае функция может неправильно сообщить о завершении операции чтения.
• Параметр lpNumberOfBytesRead должен иметь значение NULL. Используйте функцию getOverlappedResult , чтобы получить фактическое число байтов для чтения. Если параметр hFile связан с портом завершения ввода-вывода, можно также получить количество байтов, считываемых путем вызова функции GetQueuedCompletionStatus.

Синхронизация и положение файлов

Если hFile открыт с FILE_FLAG_OVERLAPPED, это асинхронный дескриптор файла; в противном случае она синхронна. Правила использования ПЕРЕКРЫТИЯ структуры немного отличаются для каждой из них, как отмечалось ранее.

Рекомендации по работе с асинхронными дескрипторами файлов:

• ReadFile может вернуться до завершения операции чтения. В этом сценарии ReadFile возвращает FALSE, а функция GetLastError возвращает ERROR_IO_PENDING, что позволяет вызывать процесс, пока система завершает операцию чтения.
• Параметр lpOverlapped не должен быть null и должен использоваться со следующими фактами.
  • Несмотря на то, что событие, указанное в структуре OVERLAPPED, устанавливается и сбрасывается автоматически системой, смещение, указанное в структуре OVERLAPPED, не обновляется автоматически.
  • ReadFile сбрасывает событие в незначаемое состояние при запуске операции ввода-вывода.
  • Событие, указанное в структуре OVERLAPPED, устанавливается в сигнальное состояние при завершении операции чтения; до этого времени операция чтения считается ожидающей.
  • Так как операция чтения начинается с смещения, указанного в структуре OVERLAPPED, и ReadFile может вернуться до завершения операции чтения на уровне системы (ожидается чтение), ни смещения, ни другой части структуры не следует изменять, освобождать или повторно использовать приложением, пока событие не будет сигнализировать (то есть, завершение чтения).
  • Если во время асинхронных операций обнаруживается конечный файл (EOF), вызов GetOverlappedResult для этой операции возвращает FALSE и GetLastError возвращает ERROR_HANDLE_EOF.

Рекомендации по работе с синхронными дескрипторами файлов:

• Если lpOverlappedNULL, операция чтения начинается с текущей позиции файла и ReadFile не возвращается до завершения операции, а система обновляет указатель файла до readFile.
• Если lpOverlapped не NULL, операция чтения начинается со смещения, указанного в структуре OVERLAPPED и ReadFile не возвращается до завершения операции чтения. Система обновляет смещение OVERLAPPED и указатель файла перед возвратом ReadFile.
• Если lpOverlappedNULL, то когда синхронная операция чтения достигает конца файла, ReadFile возвращает TRUE и задает *lpNumberOfBytesRead нулю.
• Если lpOverlapped не NULL, то когда синхронная операция чтения достигает конца файла, ReadFile возвращает FALSE и GetLastError возвращает ERROR_HANDLE_EOF.

Дополнительные сведения см. в разделе CreateFile и синхронной и асинхроннойввода-вывода.

Трубы

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

Если именованный канал считывается в режиме сообщения, а следующее сообщение больше параметра nNumberOfBytesToRead, ReadFile возвращает FALSE и GetLastError возвращает ERROR_MORE_DATA. Оставшаяся часть сообщения может быть прочитана последующим вызовом функции ReadFile или функции PeekNamedPi pe.

Если параметр lpNumberOfBytesRead равен нулю, если ReadFile возвращает TRUE на канале, то другая часть канала называется функцией WriteFile с nNumberOfBytesToWrite равным нулю.

Дополнительные сведения о каналах см. в разделе Трубы.

Операции с транзакцией

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

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

Примеры

Пример кода, показывающий, как протестировать конечный файл, см. в разделе Тестирование для окончанияфайла. Другие примеры см. в статье Создание и использование временного файла и открытие файла для чтения или записи.

Требования

См. также

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

функции управления файлами

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

ПЕРЕКРЫВАЮЩИЕСЯ

PeekNamedPipe

ReadFileEx

SetCommTimeouts

SetErrorMode

WriteFile