Функция WaitCommEvent

Функция WaitCommEvent ожидает какое-то событие, которое произойдет для заданного коммуникационного устройства. Пакет событий, которые проверяются этой функцией, содержится в маске события, связанной с дескриптором устройства.

Синтаксис

BOOL WaitCommEvent(
  HANDLE hFile,
  LPDWORD lpEvtMask,
  LPOVERLAPPED lpOverlapped
);

Параметры

hFile

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

lpEvtMask

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

Значение	Предназначение
EV_BREAK	Во время ввода данных было обнаружено прерывание.
EV_CTS	Сигнал готовности к приему (CTS) изменил состояние.
EV_DSR	Сигнал готовности модема (DSR) изменил состояние.
EV_ERR	Произошла ошибка состояния линии. Ошибкой состояния линии являются CE_FRAME, CE_OVERRUN и CE_RXPARITY.
EV_RING	Был обнаружен индикатор вызова.
EV_RLSD	Сигнал RLSD (детектор принимаемого линейного сигнала) изменил состояние.
EV_RXCHAR	Символ был принят и помещен в буфер ввода данных.
EV_RXFLAG	Символ события был принят и помещен в буфер ввода данных. Символ события определяется в структуре DCB устройства, которое обращается к последовательному порту, используя функцию SetCommState.
EV_TXEMPTY	Был отправлен последний символ из буфера вывода данных.

lpOverlapped

[in] Указатель на структуру 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').

Код примера

Пример смотри в статье Мониторинг коммуникационных событий.

Смотри также

Обзор Коммуникационные ресурсы, Функции, используемые коммуникационными ресурсами, CreateFile, DCB, GetCommMask, GetOverlappedResult, OVERLAPPED, SetCommMask, SetCommState

Размещение и совместимость WaitCommEvent
К	Windows XP	Да
л	Windows 2000 Professional	Да
и	Windows NT Workstation	Да
е	Windows Me	Да
н	Windows 98	Да
т	Windows 95	Да

С	Windows 2003 Server	Да
е	Windows 2000 Server	Да
р	Windows NT Server	Да
в
е
р
	Используемая библиотека	Kernel32.lib
	Заголовочный файл
	- объявлено в	Winbase.h
	- включено в	Windows.h
	Unicode	-
	Замечания по платформе	Не имеется

Назад в оглавление

На главную страницу

На оглавление справки