WaitCommEvent function

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

等待制定通讯设备产生一个事件.这个函数可以监视与设备句柄相关联的的事件(具体什么事件，是通过查看参数event mask。)

Syntax

C++

Copy

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

Parameters

hFile [in]

A handle to the communications device. The CreateFile function returns this handle.

通讯设备的句柄。函数CreatFile返回这个句柄。

lpEvtMask [out]

A pointer to a variable that receives a mask indicating the type of event that occurred. If an error occurs, the value is zero; otherwise, it is one of the following values.

指向一个变量的指针，这个变量表示接收到的事件类型。如果错误发生，这个值为零。否则是下列值中的一个。

Value	Meaning
EV_BREAK 0x0040	A break was detected on input .检测到输入中断。
EV_CTS 0x0008	The CTS (clear-to-send) signal changed state.准备发送数据信号 改变状态。
EV_DSR 0x0010	The DSR (data-set-ready) signal changed state. 数据装置准备就绪信号（MODEM处于可用状态） 改变状态。
EV_ERR 0x0080	A line-status error occurred. Line-status errors are CE_FRAME,CE_OVERRUN, andCE_RXPARITY.
EV_RING 0x0100	A ring indicator was detected.
EV_RLSD 0x0020	The RLSD (receive-line-signal-detect) signal changed state.
EV_RXCHAR 0x0001	A character was received and placed in the input buffer.
EV_RXFLAG 0x0002	The event character was received and placed in the input buffer. The event character is specified in the device'sDCB structure, which is applied to a serial port by using theSetCommState function.
EV_TXEMPTY 0x0004	The last character in the output buffer was sent. 输出缓存最后一个字符已输出。（TX为空）

 

lpOverlapped [in]

A pointer to an OVERLAPPED structure. This structure is required if hFile was opened withFILE_FLAG_OVERLAPPED.

一个指向OVERLAPPED结构体的指针。如果通讯设备的句柄是通过FILE_FLAG_OVERLAPPED打开的，那么这个结构体是必须的。

 

If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped parameter must not be NULL. It must point to a validOVERLAPPED structure. IfhFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped isNULL, the function can incorrectly report that the operation is complete.

如果通讯设备的句柄是通过FILE_FLAG_OVERLAPPED打开的，那么lpOverlapped这个参数不能为NULL. 它必须指向一个有效的OVERLAPPED结构体。

如果通讯设备的句柄是通过FILE_FLAG_OVERLAPPED打开的，并且lpOverlapped这个参数为NULL。这个函数所报告的相关操作将是错误的。

 

If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is not NULL, WaitCommEvent is performed as an overlapped operation. In this case, theOVERLAPPED structure must contain a handle to a manual-reset event object (created by using theCreateEvent function).

如果通讯设备的句柄是通过FILE_FLAG_OVERLAPPED打开的，并且lpOverlapped这个参数不为NULL，WaitCommEvent表现为异步输入输出操作方式。在这种情况下，OVERLAPPED结构必须包含一个 手动重置事件对象 的句柄（由CreateEvent函数产生的）。

 

If hFile was not opened with FILE_FLAG_OVERLAPPED, WaitCommEvent does not return until one of the specified events or an error occurs.

如果通讯设备的句柄不是以FILE_FLAG_OVERLAPPED方式打开的（也就是以同步的方式打开的），WaitCommEvent不会有返回值，除非指定的事件产生或是有错误产生。

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, callGetLastError.

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 theSetCommMask and GetCommMask functions.

If the overlapped operation cannot be completed immediately, the function returnsFALSE and theGetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing in the background. When this happens, the system sets thehEvent member of theOVERLAPPED structure to the not-signaled state before WaitCommEvent returns, and then it sets it to the signaled state when one of the specified events or an error occurs. The calling process can use one of thewait functions to determine the event object's state and then use the GetOverlappedResult function to determine the results of theWaitCommEvent operation.GetOverlappedResult reports the success or failure of the operation, and the variable pointed to by thelpEvtMask parameter is set to indicate the event that occurred.

If a process attempts to change the device handle's event mask by using the SetCommMask function while an overlapped WaitCommEvent operation is in progress,WaitCommEvent returns immediately. The variable pointed to by thelpEvtMask parameter is set to zero.

Examples

For an example, see Monitoring Communications Events.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Header	Winbase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

See also

Communications Functions Communications Resources CreateFile DCB GetCommMask GetOverlappedResult OVERLAPPED SetCommMask SetCommState

 

 

Send comments about this topic to Microsoft

Build date: 4/16/2013

Community Additions

ADD

Clarification about "failure", ERROR_IO_PENDING and blocking

Regarding the phrase "If the overlapped operation cannot be completed immediately": This is somewhat misleading, because it's not a matter of whether this operation "can" or "cannot" complete. Rather, it's whether it's "allowed to block" based on whether the port was opened with FILE_FLAG_OVERLAPPED. If it was, then this Wait function, despite its name, is not allowed to block.

What it really means is "if there are no events to report, and the communication port was opened in overlapped mode, then this will return false and not block. If blocking is desired then you will need to wait on the actual event object contained within the OVERLAPPED structure by using GetOverlappedResult". This function will remember the original pointer passed in the lpEvtMask parameter, and will update it when it signals the event.