| BOOL WaitCommEvent(hCommDev, lpdwEvtMask, lpo) | |||||
| HANDLE hCommDev; | /* identifies the comm device | */ | |||
| LPDWORD lpdwEvtMask; | /* address for satisfied condition | */ | |||
| LPOVERLAPPED lpo; | /* overlapped structure | */ | |||
The WaitCommEvent function waits for any of the events in the event mask for the specified communications device.
hCommDev
Specifies the communication device to wait for. The CreateFile function returns this value.
lpdwEvtMask
Points to a variable that receives a mask indicating the condition that satisfied the wait. The mask has one of the following values:
| Value | Meaning |
| EV_BREAK | ||
| Sets when a break is detected on input. | ||
| EV_CTS | ||
| Sets when the clear-to-send (CTS) signal changes state. | ||
| EV_DSR | ||
| Sets when the data-set-ready (DSR) signal changes state. | ||
| EV_ERR | ||
| Sets when a line-status error occurs. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY. | ||
| EV_RING | ||
| Sets when a ring indicator is detected. | ||
| EV_RLSD | ||
| Sets when the receive-line-signal-detect (RLSD) signal changes state. | ||
| EV_RXCHAR | ||
| Sets when any character is received and placed in the receive queue. | ||
| EV_RXFLAG | ||
| Sets when the event character is received and placed in the receive queue. The event character is specified in the device's control block. | ||
| EV_TXEMPTY | ||
| Sets when the last character in the transmit queue is sent. | ||
lpo
Points to an OVERLAPPED structure to be used with the request.
If hCommDev was opened with FILE_FLAG_OVERLAPPED, the WaitCommEvent function may return before the wait completes. In this case, this function returns FALSE and the GetLastError function returns ERROR_IO_PENDING to allow the caller to continue processing while the operation completes. The event specified in the OVERLAPPED structure will be set to the signalled state when the wait is satisfied.
The OVERLAPPED structure has the following form:
typedef struct _OVERLAPPED { /* o */
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
typedef OVERLAPPED *LPOVERLAPPED;
If the function is successful, the return value is TRUE, and lpdwEvtMask indicates the condition that satisified the wait. If an error occurred or the wait operation is overlapped and has not yet completed, the return value is FALSE. Use the GetLastError function to obtain extended error information.
If this function specifies an overlapped wait (lpo is not NULL), the function returns FALSE and the GetLastError function returns ERROR_IO_PENDING if the operation has not yet completed. The GetOverlappedResult function can be used to obtain the results of the overlapped wait.
If a communication device's event mask is changed by the SetCommMask function while the device is waiting, the wait will end and the WaitCommEvent function will return immediately. The variable at lpdwEvtMask will be zero.
ClearCommBreak, ClearCommError, GetCommMask, GetCommState, GetCommTimeouts, PurgeComm, SetCommBreak, SetCommMask, SetCommState, SetCommTimeouts