WaitCommEvent

作用：為一個特指的通信設備等待一個事件發生，該函式所監控的事件是與該設備句柄相關聯的一系列事件。

基本介紹

• 中文名：WaitCommEvent
• Value：Meaning
• EV_BREA：在輸入過程中發生中斷
• EV_CTS0x0008：CTS線上的信號改變狀態等

原型

BOOL WINAPI WaitCommEvent(

__in HANDLEhFile,

__out LPDWORDlpEvtMask,

__in LPOVERLAPPEDlpOverlapped

);

主要參數

hFile：指向通信設備的一個句柄，該句柄應該是由 CreateFile函式返回的。

lpEvtMask：一個指向DWORD的指針。如果發生錯誤，pEvtMask指向0，否則指向以下的某一事件

EV_DSR; 0x0010	The DSR (data-set-ready) signal changed state. DSR(數據裝置就緒)信號改變狀態。
EV_ERR; 0x0080	A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_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'sDCBstructure, which is applied to a serial port by using theSetCommStatefunction.
EV_TXEMPTY; 0x0004	The last character in the output buffer was sent.（輸出緩衝區的數據全部傳送出去)

lpOverlapped：指向OVERLAPPED結構體的一個指針。如果hFile是用異步方式打開的（在CreateFile（）函式中，第三個參數設定為FILE_FLAG_OVERLAPPED），lpOverlapped不能指向一個空OVERLAPPED結構體，而是與Readfile（）和WriteFile（）中的OVERLAPPED參數為同一個參數。如果hFile是用異步方式打開的，而lpOverlapped指向一個空的OVERLAPPED結構體，那么函式會錯誤地報告，等待的操作已經完成（而此時等待的操作可能還沒有完成）。

如果hFile是用異步方式打開的，而lpOverlapped指向一個非空的OVERLAPPED結構體，那么函式WaitCommEvent被默認為異步操作，馬上返回。這時，OVERLAPPED結構體必須包含一個由CreateEvent（）函式返回的手動重置事件對象的句柄hEven。

如果hFile是用同步方式打開的，那么函式WaitCommEvent不會返回，直到要等待的事件發生。

返回值：

如果函式成功，返回非零值，否則返回0。要得到錯誤信息，可以調用GetLastError函式。

備註：

WaitCommEvent函式為指定的通信資源監聽一系列的Event,這些Event可以由SetcommMask和GetcommMask函式來設定和查詢。

如果異步操作不能馬上完成，那么該函式會返回一個FALSE，同時GetLastError函式可以截獲錯誤碼ERROR_IO_PENDING（#define ERROR_IO_PENDING 997），表示操作轉到後台運行。在WaitCommEvent函式返回之前，系統將OVERLAPPED結構中的hEven句柄設定為無信號狀態；當WaitCommEvent函式所等待的任何一個Event發生後，系統將OVERLAPPED結構中的hEven句柄設定為有信號狀態，同時將所發生事件賦給lpEvtMask。

父進程可以根據lpEvtMask來做出相應的事件處理，然後也可以調用GetOverlappedResult函式來判斷WaitCommEvent的操作是否成功。

如果WaitCommEvent函式在後台運行的時候，進程企圖想通過SetcommMask函式來改變當前設備的Event，那么WaitCommEvent函式馬上返回，lpEvtMask指向0。

舉例：

The following example code opens the serial port for overlapped I/O, creates an event mask to monitor CTS and DSR signals, and then waits for an event to occur. TheWaitCommEventfunction should be executed as an overlapped operation so the other threads of the process can perform I/O operations during the wait.

#include <windows.h>

#include <assert.h>

#include <stdio.h>

void main( )

{

HANDLE hCom;

OVERLAPPED o;

BOOL fSuccess;

DWORD dwEvtMask;

hCom = CreateFile( TEXT("COM1"),

GENERIC_READ | GENERIC_WRITE,

0, // exclusive access

NULL, // default security attributes

OPEN_EXISTING,

FILE_FLAG_OVERLAPPED,

NULL);

if (hCom == INVALID_HANDLE_VALUE)

{// Handle the error.

printf("CreateFile failed with error %d.\n", GetLastError());

return;

}

// Set the event mask.

fSuccess =SetCommMask(hCom, EV_CTS | EV_DSR);

if (!fSuccess)

{

// Handle the error.

printf("SetCommMask failed with error %d.\n", GetLastError());

return;

}

// Create an event object for use by WaitCommEvent.

o.hEvent = CreateEvent(

NULL, // default security attributes

TRUE, // manual-reset event

FALSE, // not signaled

NULL // no name

);

// Initialize the rest of the OVERLAPPED structure to zero.

o.Internal = 0;

o.InternalHigh = 0;

o.Offset = 0;

o.OffsetHigh = 0;

assert(o.hEvent);

if (WaitCommEvent(hCom, &dwEvtMask, &o))

{

if (dwEvtMask & EV_DSR)

{

// To do.

}

if (dwEvtMask & EV_CTS)

{

// To do.

}

}

else

{

DWORD dwRet = GetLastError();

if( ERROR_IO_PENDING == dwRet)

{

printf("I/O is pending...\n");

// To do.

}

else

printf("Wait failed with error %d.\n", GetLastError());

}

}