Using Communication Events

A communication event is a notification sent by Windows CE to an application when a significant incident occurs. Using the WaitCommEvent function, an application can block a thread until a specific event occurs. A call to the SetCommMask function specifies which event or events must occur before processing can continue. When more than one event is specified, any single specified event that occurs causes WaitCommEvent to return.

For example, this mechanism enables an application to find out when data arrives at the serial port. By waiting for a communication event that indicates data is present, an application avoids forestalling the serial port with a call to the ReadFile function that waits for data to arrive. ReadFile is called only when there is data to read.

The following table lists the communication events that an application can use with the WaitCommEvent function.

Event
Description
EV_BREAK A break occurred on input.
EV_CTS The CTS signal changed state.
EV_DSR The DSR signal changed state.
EV_ERR A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_RING A ring indicator was detected.
EV_RLSD The receive-line-signal-detect signal changed state.
EV_RXCHAR A character was received and placed in the input buffer.
EV_RXFLAG The event character was received and placed in the input buffer.
EV_TXEMPTY The last character in the output buffer was sent.

    To use communication events

  1. Specify events to look for with a call to the SetCommMask function.
  2. Call the WaitCommEvent function and specify which events cause this function to return. When an application specifies more than one event, the lpEvtMask parameter points to a variable that identifies the event that caused WaitCommEvent to return.
  3. After WaitCommEvent returns, use a loop that calls ReadFile until all received data has been read.
  4. Call SetCommMask again to specify which events to look for.

SetCommMask is the first call in a loop that applications generally use to monitor a serial port and read data. The following code example shows how to use communication events for this purpose.

BYTE Byte;
DWORD dwBytesTransferred;

// Specify a set of events to be monitored for the port.
SetCommMask (hPort, EV_RXCHAR | EV_CTS | EV_DSR | EV_RLSD | EV_RING);

while (hPort != INVALID_HANDLE_VALUE) 
{
  // Wait for an event to occur for the port.
  WaitCommEvent (hPort, &dwCommModemStatus, 0);

  // Re-specify the set of events to be monitored for the port.
  SetCommMask (hPort, EV_RXCHAR | EV_CTS | EV_DSR | EV_RING);

  if (dwCommModemStatus & EV_RXCHAR) 
  {
    // Loop for waiting for the data.
    do 
    {
      // Read the data from the serial port.
      ReadFile (hPort, &Byte, 1, &dwBytesTransferred, 0);

      // Display the data read.
      if (dwBytesTransferred == 1)
        ProcessChar (Byte);

    } while (dwBytesTransferred == 1);
  }