Функция WaitCommEvent (winbase.h)

Статья
08/27/2023

Ожидает возникновения события для указанного устройства связи. Набор событий, отслеживаемых этой функцией, содержится в маске событий, связанной с дескриптором устройства.

Синтаксис

BOOL WaitCommEvent(
  [in]  HANDLE       hFile,
  [out] LPDWORD      lpEvtMask,
  [in]  LPOVERLAPPED lpOverlapped
);

Параметры

[in] hFile

Дескриптор устройства связи. Функция CreateFile возвращает этот дескриптор.

[out] lpEvtMask

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

Значение	Значение
EV_BREAK 0x0040	Обнаружен разрыв на входе.
EV_CTS 0x0008	Сигнал CTS (очистить для отправки) изменил состояние.
EV_DSR 0x0010	Сигнал DSR (data-set-ready) изменил состояние.
EV_ERR 0x0080	Произошла ошибка состояния строки. Ошибки состояния строки: CE_FRAME, CE_OVERRUN и CE_RXPARITY.
EV_RING 0x0100	Обнаружен индикатор вызова.
EV_RLSD 0x0020	Изменено состояние сигнала RLSD (receive-line-signal-detect).
EV_RXCHAR 0x0001	Символ получен и помещен во входной буфер.
EV_RXFLAG 0x0002	Символ события получен и помещен во входной буфер. Символ события указывается в структуре DCB устройства, которая применяется к последовательному порту с помощью функции SetCommState .
EV_TXEMPTY 0x0004	Последний символ в выходном буфере был отправлен.

[in] lpOverlapped

Указатель на структуру OVERLAPPED . Эта структура является обязательной, если файл hFile был открыт с помощью FILE_FLAG_OVERLAPPED.

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

Если hFile был открыт с FILE_FLAG_OVERLAPPED и lpOverlapped не имеет значения NULL, WaitCommEvent выполняется как перекрываемая операция. В этом случае структура OVERLAPPED должна содержать дескриптор объекта события сброса вручную (созданного с помощью функции CreateEvent ).

Если hFile не был открыт с FILE_FLAG_OVERLAPPED, WaitCommEvent не возвращается до тех пор, пока не произойдет одно из указанных событий или ошибка.

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

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

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

Функция WaitCommEvent отслеживает набор событий для указанного ресурса связи. Чтобы задать и запросить текущую маску события ресурса связи, используйте функции SetCommMask и GetCommMask .

Если перекрывающаяся операция не может быть завершена немедленно, функция возвращает FALSE , а функция GetLastError возвращает ERROR_IO_PENDING, указывая, что операция выполняется в фоновом режиме. В этом случае система устанавливает для элемента hEvent структуры OVERLAPPED состояние без сигнала перед возвратом WaitCommEvent , а затем устанавливает его в состояние сигнала при возникновении одного из указанных событий или ошибки. Вызывающий процесс может использовать одну из функций ожидания для определения состояния объекта события, а затем использовать функцию GetOverlappedResult для определения результатов операции WaitCommEvent . GetOverlappedResult сообщает об успешном или неудачно выполненной операции, а переменная, на которую указывает параметр lpEvtMask , указывает на произошедшее событие.

Если процесс пытается изменить маску событий дескриптора устройства с помощью функции SetCommMask во время выполнения перекрывающейся операции WaitCommEvent , функция WaitCommEvent возвращается немедленно. Переменная, на которую указывает параметр lpEvtMask , имеет значение 0.

Примеры

Пример см. в разделе Мониторинг событий связи.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll