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	偵測到鈴聲指示器 (Indicator)。
EV_RLSD 0x0020	RLSD (接收線訊號偵測) 訊號已變更狀態。
EV_RXCHAR 0x0001	會接收字元並放到輸入緩衝區。
EV_RXFLAG 0x0002	已接收事件字元，並將其放在輸入緩衝區中。事件字元是在裝置的 DCB 結構中指定，它會使用 SetCommState 函式套用至序列埠。
EV_TXEMPTY 0x0004	輸出緩衝區中的最後一個字元已傳送。

[in] lpOverlapped

重迭結構的指標。如果 hFile 是以 FILE_FLAG_OVERLAPPED開啟，則需要此結構。

如果 hFile 是以 FILE_FLAG_OVERLAPPED開啟， 則 lpOverlapped 參數不得為 Null。它必須指向有效的重迭結構。如果 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，表示作業正在背景執行。發生這種情況時，系統會在WaitCommEvent傳回之前，將OVERLAPPED結構的hEvent成員設定為未收到訊號的狀態，然後在發生其中一個指定的事件或錯誤時，將它設定為已發出訊號的狀態。呼叫進程可以使用其中一個等候函式來判斷事件物件的狀態，然後使用 GetOverlappedResult 函式來判斷 WaitCommEvent 作業的結果。 GetOverlappedResult 會報告作業的成功或失敗，而 lpEvtMask 參數所指向的變數會設定為指出發生的事件。

如果進程嘗試在重迭的 WaitCommEvent作業進行時使用SetCommMask函式來變更裝置控制碼的事件遮罩，WaitCommEvent會立即傳回。 lpEvtMask參數所指向的變數會設定為零。

範例

如需範例，請參閱監視通訊事件。

規格需求


最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll