Using Communication Events

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

A communication event is a notification sent by Windows Embedded 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 are communication events 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.

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

Note

The following code assumes that timeouts are set to something fairly short. If timeouts are not set, the code sample blocks on ReadFile forever.

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);
  }

See Also

Concepts

Programming Serial Connections