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 (数据集就绪) 信号更改状态。
EV_ERR 0x0080	发生行状态错误。行状态错误CE_FRAME、CE_OVERRUN和CE_RXPARITY。
EV_RING 0x0100	检测到振铃指示。
EV_RLSD 0x0020	RLSD (接收行信号检测) 信号更改状态。
EV_RXCHAR 0x0001	接收到了一个字符并将其放入了输入缓冲区。
EV_RXFLAG 0x0002	事件字符已接收并放置在输入缓冲区中。事件字符在设备的 DCB 结构中指定，该结构通过使用 SetCommState 函数应用于串行端口。
EV_TXEMPTY 0x0004	输出缓冲区中的最后一个字符已发送。

[in] lpOverlapped

指向 OVERLAPPED 结构的指针。如果使用 FILE_FLAG_OVERLAPPED 打开 hFile ，则需要此结构。

如果使用 FILE_FLAG_OVERLAPPED 打开 hFile，则 lpOverlapped 参数不得为 NULL。它必须指向有效的 OVERLAPPED 结构。如果使用 FILE_FLAG_OVERLAPPED 打开 hFile 并且 lpOverlapped 为 NULL，则该函数可能会错误地报告操作已完成。

如果使用 FILE_FLAG_OVERLAPPED 打开 hFile 并且 lpOverlapped 不为 NULL，则 WaitCommEvent 作为重叠操作执行。在这种情况下， OVERLAPPED 结构必须包含使用 CreateEvent 函数) 创建的手动重置事件对象的句柄 (。

如果未使用 FILE_FLAG_OVERLAPPED 打开 hFile，则 WaitCommEvent 在指定的事件之一或发生错误之前不会返回。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

WaitCommEvent 函数监视指定通信资源的一组事件。若要设置和查询通信资源的当前事件掩码，请使用 SetCommMask 和 GetCommMask 函数。

如果重叠操作无法立即完成，则函数返回 FALSE ， GetLastError 函数返回 ERROR_IO_PENDING，指示操作正在后台执行。发生这种情况时，系统会在 WaitCommEvent 返回之前将 OVERLAPPED 结构的 hEvent 成员设置为未发出信号的状态，然后在指定事件之一或发生错误时将其设置为已发出信号的状态。调用进程可以使用其中一个等待函数来确定事件对象的状态，然后使用 GetOverlappedResult 函数确定 WaitCommEvent 操作的结果。 GetOverlappedResult 报告操作的成功或失败，并将 lpEvtMask 参数指向的变量设置为指示发生的事件。

如果在重叠的 WaitCommEvent 操作正在进行时，某个进程尝试使用 SetCommMask 函数更改设备句柄的事件掩码，则 WaitCommEvent 将立即返回。 lpEvtMask 参数指向的变量设置为零。

示例

有关示例，请参阅监视通信事件。

要求


最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll