WaitCommEvent function

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.

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.

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.
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'sDCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY 0x0004	The last character in the output buffer was sent.

 

lpOverlapped [in]

A pointer to an OVERLAPPED structure. This structure is required ifhFile was opened with 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. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the function can incorrectly report that the operation is complete.

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).

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

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 the GetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing in the background. When this happens, the system sets thehEvent member of the OVERLAPPED structure to the not-signaled state beforeWaitCommEvent 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 the wait functions to determine the event object's state and then use theGetOverlappedResult function to determine the results of the WaitCommEvent 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.

作用：为一个特指的通信设备等待一个事件发生，该函数所监控的事件是与该设备句柄相关联的一系列事件。　

原型：

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

参数：　　

hFile：指向通信设备的一个句柄，该句柄应该是由 CreateFile函数返回的。　　

lpEvtMask：一个指向DWORD的指针。如果发生错误，pEvtMask指向0，否则指向以下的某一事件

Value	Meaning
EV_BREAK 0x0040	A break was detected on input.（在输入过程中发生中断)
EV_CTS 0x0008	The CTS (clear-to-send) signal changed state.(CTS线上的信号改变状态)
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'sDCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY 0x0004	The last character in the output buffer was sent.（输出缓冲区的数据全部发送出去)

        lpOverlapped ：指向OVERLAPPED结构体的一个指针。如果hFile是用异步方式打开的（在CreateFile（）函数中，第三个参数设置为FILE_FLAG_OVERLAPPED），lpOverlapped 不能指向一个空OVERLAPPED结构体，而是与Readfile（）和WreteFile（）中的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。

Monitoring Communications Events

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. TheWaitCommEvent function 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 <tchar.h>
#include <assert.h>
#include <stdio.h>

void _tmain(
            int argc, 
            TCHAR *argv[]
           )
{
    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());
    }
}

WaitCommEvent function