ReadFile() - функция Win 32 API

Все примеры приведены для среды разработки Embarcadero RAD Studio 11 (C++ Builder)

В ОС Windows работа с последовательными и параллельными портами ввода-вывода производится как с объектами файловой системы. Для этого используются стандартные функции Win32 API:

- CreateFile() - открывает порт и получает его дескриптор (HANDLE).

- CloseHandle() - закрывает ранее открытый порт по его дескриптору.

- ReadFile() - читает данные из порта.

- WriteFile() - отправляет данные в порт.

Описание функции ReadFile()

Считывает данные из указанного файла или устройства ввода-вывода в синхронном или асинхронном режиме. Прототип функции находится в файле fileapi.h.

WINBASEAPI  _Must_inspect_result_  BOOL  WINAPI  ReadFile(
   _In_  HANDLE  hFile,
   _Out_writes_bytes_to_opt_(nNumberOfBytesToRead, *lpNumberOfBytesRead) __out_data_source(FILE)  LPVOID  lpBuffer,
   _In_  DWORD  nNumberOfBytesToRead,
   _Out_opt_  LPDWORD  lpNumberOfBytesRead,
   _Inout_opt_  LPOVERLAPPED  lpOverlapped
);

Параметры

HANDLE

hFile

Указатель типа void на дескриптор открытого порта.

typedef  void *HANDLE;

LPVOID

lpBuffer

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

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

typedef  void far *LPVOID;

DWORD

nNumberOfBytesToRead

Максимальное количество ожидаемых к приёму байтов.

LPDWORD

lpNumberOfBytesRead

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

Функция ReadFile() обнуляет количество принятых байтов перед началом работы и в случае обработки ошибок.

Для асинхронной передачи это значение должно быть NULL и должна использоваться структура OVERLAPPED.

В Windows 7 этот параметр всегда не NULL.

LPOVERLAPPED

lpOverlapped

Указатель на структуру OVERLAPPED.

Структура OVERLAPPED содержит сведения для асинхронной передачи. Должна быть уникальна для каждого hFile - дескриптора открытого порта. При этом порт должен быть открыт с параметром FILE_FLAG_OVERLAPPED.

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

BOOL

При успешном вызове функции в синхронном режиме возвращаемое значение будет ненулевым (true), при ошибке функция возвращает 0 (false). Информацию о ошибке можно получить, вызвав функцию GetLastError().

При работе в асинхронном режиме функция возвращает 0 (false) с кодом GetLastError() равным ERROR_IO_PENDING. Это не является ошибкой а сигнализирует, что операция чтения работает асинхронно и ожидает завершения приёма данных.

Примечание

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