WaitCommEvent

This function waits for an event to occur for a specified communications device. The set of events that are monitored by WaitCommEvent is contained in the event mask associated with the device handle.

At a Glance

Header file: Winbase.h
Windows CE versions: 1.0 and later

Syntax

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

Parameters

hFile

[in] Handle to the communications device. The CreateFile function returns this handle.

lpEvtMask

[out] Long pointer to a 32-bit variable that receives a mask indicating the events that occurred. If an error occurs, the value is zero; otherwise, it is one or more of the following values:

Value Description
EV_BREAK A break was detected on input.
EV_CTS The CTS (clear-to-send) signal changed state.
EV_DSR The DSR (data-set-ready) signal changed state.
EV_ERR A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_POWER Power event, which is generated whenever the device is powered on.
EV_RING A ring indicator was detected.
EV_RLSD The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR A character was received and placed in the input buffer.
EV_RXFLAG The event character was received and placed in the input buffer. The event character is specified in the device’s DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY The last character in the output buffer was sent.

lpOverlapped

[in] Ignored; set to NULL.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The WaitCommEvent function monitors a set of events for a specified communications resource. To set and query the current event mask of a communications resource, use the SetCommMask and GetCommMask functions. When a communications event that is set by SetCommMask occurs, WaitCommEvent returns.

See Also

CreateFile, DCB, GetCommMask, SetCommMask, SetCommState