Структура COMMTIMEOUTS - параметры временных задержек COM-порта

Описание структуры COMMTIMEOUTS

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

Структура COMMTIMEOUTS описывает параметры временнЫх задержек COM-порта.

(Ударение ставится на последний слог (букву Ы). Описываются задержки во времени, а не то что они могут быть постоянными или врЕменными).

typedef  struct  _COMMTIMEOUTS {
    DWORD ReadIntervalTimeout;          /* Maximum time between read chars. */
    DWORD ReadTotalTimeoutMultiplier;   /* Multiplier of characters.        */
    DWORD ReadTotalTimeoutConstant;     /* Constant in milliseconds.        */
    DWORD WriteTotalTimeoutMultiplier;  /* Multiplier of characters.        */
    DWORD WriteTotalTimeoutConstant;    /* Constant in milliseconds.        */
} COMMTIMEOUTS,  *LPCOMMTIMEOUTS;

Описание полей структуры COMMTIMEOUTS

ReadIntervalTimeout

Таймаут между двумя последовательными символами, принимаемыми по линии связи, для завершения операции чтения.

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

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

При значении поля равным MAXDWORD, вместе с нулевыми значениями полей ReadTotalTimeoutConstant и ReadTotalTimeoutMultiplier, указывают на немедленный возврат из операции чтения с передачей буфера вызывающей программе, даже если передача не закончена.

Таймаут начинает отсчитываться с момента приёма первого бита символа. Точнее сказать что ReadIntervalTimeout - интервал между началами двух последовательных символов, т.е. в него входит и время передачи одного символа.

ReadTotalTimeoutMultiplier

Множитель для расчета общего таймаута для операции чтения.

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

ReadTotalTimeoutConstant

Константа для расчета общего таймаута для операции чтения.

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

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

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

WriteTotalTimeoutMultiplier

Множитель для расчета общего таймаута для операции записи.

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

WriteTotalTimeoutConstant

Константа для расчета общего таймаута для операции записи.

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

Для каждой операции записи это значение добавляется к произведению множителя WriteTotalTimeoutMultiplier и количества записываемых символов.

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

Получение информации о структуре COMMTIMEOUTS

Получить информацию о структуре COMMTIMEOUTS можно вызвав функцию GetCommTimeouts(). Прототип функции находится в файле winbase.h.

WINBASEAPI  BOOL  WINAPI  GetCommTimeouts(
   _In_   HANDLE          hFile,
   _Out_  LPCOMMTIMEOUTS  lpCommTimeouts
);

- HANDLE hFile - указатель типа void на дескриптор открытого порта.

typedef  void *HANDLE;     //- winnt.h

- LPCOMMTIMEOUTS lpCommTimeouts - указатель на структуру COMMTIMEOUTS.

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

Модификаторы вызова функции и аргументов:

- WINBASEAPI (он же DECLSPEC_IMPORT, или __declspec(dllimport)) - указывает на класс хранилища функции. Позволяет получить доступ к объектам библиотеки DLL.

- WINAPI (он же __stdcall) - соглашение о вызове функций Win32 API: аргументы передаются справа налево через стек; очистка стека ложится на вызываемую функцию; возвращаемое значение в регистре eax.

- _In_ и _Out_ - макросы, которые вызываются только при использовании SAL2.0 — языка заметок для драйверов Windows (способ описания свойств функций, параметров, возвращаемых значений, структур и полей структуры). В данном случае не используются.

Сохранение информации в структуре COMMTIMEOUTS

Сохранить информацию в структуре COMMTIMEOUTS можно вызвав функцию SetCommTimeouts(). Прототип функции находится в файле winbase.h.

WINBASEAPI  BOOL  WINAPI  SetCommTimeouts(
   _In_ HANDLE hFile,
   _In_ LPCOMMTIMEOUTS lpCommTimeouts
);

Вызов функции в момент передачи может вызвать искажение передаваемых данных. Параметры и возвращаемые значения аналогичны GetCommTimeouts().