Serial Communication Under Win32
Eric Woodruff
Serial ports used to be easy to program on a PC. Then they got more complex, then unreachable. Now they can be made to look simple again.
Introduction
Anyone porting 16-bit serial communication code to 32-bit Windows NT or Windows 95 faces a common problem: the familiar methods of implementing communication are at the very least different and at the worst, no longer present. Some of the Win32 API function for setting up the communications port have not changed with respect to their Win16 counterparts. However, the functions used to open, close, read, and write to the port do not exist, nor do the messages generated by the driver when an I/O event occurs. If, like me, you move from 16-bit DOS right into 32-bit Windows, the change is even more pronounced, as you can no longer use an interrupt routine to perform serial communications and you must learn new methods of performing the required tasks of serial I/O.
Having said that, the Win32 API does offer improved support for communication devices. Win32 eliminates the need to deal with communication devices in a non-standard way; it also eliminates the need to deal with the hardware directly. Instead, you perform serial communication with the standard Win32 file I/O functions. For those moving from 16-bit Windows, Table 1 lists the Win32 API equivalents for the 16-bit API functions.
| 16-bit API | Win-32 API |
|---|---|
| OpenComm | CreateFile |
| CloseComm | CloseHandle |
| FlushComm | PurgeComm |
| GetComError | ClearCommError |
| ReadComm | ReadFile |
| WriteComm | WriteFile |
| SetCommEventMask | SetCommMask |
| GetCommEventMask | GetCommMask |
| EnableCommEventNotification | WaitComEvent* |
| UngetCommChar | -None- |
| *WaitCommEvent will not post WM_COMMNOTIFY messages | |
Table 1: 16-bit Communication Functions and their Win32 Equivalents
While the Win32 API does make it simple to open a port and start sending and receiving data, I soon found that there is more to serial I/O than that. For example, as always, you must configure the port with the right set of options and timeout values for these operations to work as expected. This article presents a class that encapsulates the Win32 API functions used for serial communication and simplifies their use. This class also provides some member functions that make it easy to start and stop a separate thread for sending and receiving data. The source code and some sample programs that demonstrate how the class can be used can be downloaded from my web site. I developed and tested the code using Borland C++ 5.01 and Visual C++ 4.2.
Class CSerialPort
Listing 1 (SerialPort.h) shows the class declaration for
CSerialPort and its supporting definitions. The class consists of some protected data members that
track the state of the object, a set of configuration functions, a set of I/O functions, and wrappers for the
Win32 API functions relating to serial communication. The class also provides built-in support for overlapped I/O
and for starting and stopping a separate thread to send and/or receive data via the port. More often than not,
the basic class can be used as is unless there is a need for specialized read/write operations. In those cases,
it's fairly easy to derive a class from CSerialPort and override one or more of its virtual
functions. This will enable you to set up customized, multi-threaded, serial communications. To date, I have
not needed the class's overlapped read/write features beyond the polled I/O support provided by the
WaitCommEvent and CheckForCommEvent functions. Most of my applications have made good
use of the StartCommThread function, though.
To create a communication object, simply pass its constructor the name of the port you want to open. By
default CSerialPort initializes the port for 19,200 bps, no parity, eight data bits, one stop bit,
hardware flow control, no read timeouts, one-second write timeouts, and enables monitoring of EV_RXCHAR
events. Once the object is created, you can alter these settings with the configuration member functions shown
in Table 2. The Win32 wrapper functions such as SetCommState, SetupComm,
and SetCommTimeouts can be used if necessary, but the functions in Table 2 take
care of many of the low-level details associated with initializing the required structures. Each of the
functions in Table 2 also combines several steps into a single function call. Once the port
is opened and configured, use the ReadCommBlock and WriteCommBlock member functions to
send and receive data.
| Function | Purpose |
|---|---|
| SetBaudRate | Sets the baud rate (bps) |
| SetParityDataStop | Change parity, data bits, stop bit settings |
| SetBufferSizes | Change input/output buffer sizes used by Windows |
| SetReadTimeouts | Change the read timeouts |
| SetWriteTimeouts | Change the write timeouts |
| SetCommMask | Specify which set of comm events to monitor |
Table 2: CSerialPort Configuration Functions
Listing 2 (Terminal.cpp) shows the ubiquitous dumb terminal
program, reworked to take advantage of the 32-bit environment and utilize the basic CSerialPort
class. The DumbTerminal function calls the StartCommThread member function to start a
separate thread to handle incoming serial data (signaled by the EV_RXCHAR communication events)
while the main thread waits for keyboard input and writes it out to the port. Note that by allowing a separate
thread to handle incoming serial port data you can eliminate the need to continuously poll for both forms of
input in the main thread. Thus the application consumes less CPU time without the programmer expending any
special effort.
TermPoll.cpp, included on the CUJ FTP site, is a less efficient implementation of Terminal.cpp that
illustrates this point. In the TermPoll.cpp version, the Sleep function must be called to introduce
a slight delay in the main loop. This prevents the CPU from reaching 100% continuous utilization. Using
separate threads instead to send and receive data especially makes sense in a GUI application; the main thread
remains responsive to user-interface events.
A CSerialPort object can receive notification of certain communication events. To select which
notifications your object will receive, use the SetCommMask member function. The events are
specified by ORing together constants such as EV_RXCHAR, EV_ERR, etc. defined in
WINBASE.H. When constructed, the class enables EV_RXCHAR automatically, so if that's the only
notification you need, you don't need to call SetCommMask in your application.
Selecting which notifications the object is to receive is different than enabling the object to actually
receive notification. After selecting the events of interest with SetCommMask, you must enable the
object to receive notification by calling WaitCommEvent. This situation is analogous to setting an
interrupt mask and then later enabling interrupts by executing a special instruction. I did not implement
WaitCommEvent quite like its API equivalent in Win32. My version splits the API call into two
separate functions. Member function WaitCommEvent should be used to enable notification; use
CheckForCommEvent to see if any have occurred.
I implemented these functions this way to enable a program to either block while waiting for an event to
occur (by calling CheckForCommEvent(TRUE)) or poll for events as needed (CheckForCommEvent(FALSE)).
The return value is a bit mask of the events that have occurred; it is zero if none are available or an error
occurred. As with the Win32 API, WaitCommEvent must be called again to re-enable event notification
after CheckForCommEvent returns a value other than zero. Refer to the CommReader
thread function in Listing 2 for an example of their use.
The GUITerm Example
The GUITerm example demonstrates the use of CSerialPort in an MFC application. It provides a
dumb terminal much like the console mode example and it can also perform a basic XMODEM file transfer. This
example also demonstrates stopping and restarting a thread function for the port object and a way to use timeouts
on read operations. The application uses the document/view model. In this case, the document manages the serial
port object and the view simply displays received data and passes key presses on to the document for
transmission. When the Connect option is chosen, the document object opens the serial port and starts a thread
to handle incoming data. This approach is similar to that of the Terminal.cpp example presented above. The
difference here is that when data arrives, the receiver thread sends a WM_COMMDATA message (defined
by the application as WM_USER + 500) to the view object, which causes it to insert the received data
into the edit control used for display purposes. This application behaves somewhat like 16-bit Windows, in which
the communications driver generates a WM_COMMNOTIFY event when data arrives.
The XMODEM protocol used for the file transfer requires specific timeout values for its read and write operations. The application temporarily alters the port's timeout settings for the duration of the transfer and resets them afterwards. Under Windows, all communications resources have an associated set of timeout parameters that affect the behavior of read and write operations. Timeouts can cause a read or write operation to finish even though the specified number of characters have not been read or written. When this occurs, it is not treated as an error. The read or write function's return value indicates success but the count of bytes actually read or written will be less than what was requested.
There are two types of timeouts: interval timeouts and total timeouts. Read operations can utilize either or both forms of timeout. Write operations only use total timeouts. An interval timeout occurs when the time between the receipt of any two characters exceeds a specified number of milliseconds. Timing starts when the first character is received and is restarted when each new character arrives. A total timeout occurs when the total amount of time consumed by a read or write operation exceeds a calculated number of milliseconds. Timing starts immediately when the I/O operation begins. The number of milliseconds is calculated as follows:
Total_Timeout = (Multiplier * Number_Of_Bytes) + Constant
The use of a multiplier value allows for longer timeouts based on the number of bytes being read or written. If you do not need both a multiplier and a constant, you can set the unwanted parameter to zero. If both parameters are zero, total timeouts are disabled for the given operation and the read or write will not return until all bytes have been read or written.
Table 3 summarizes the various values and combinations of valid read timeouts. Because read operations can utilize either or both forms, you must take extra care to ensure that they are set correctly for your application. Setting the read timeouts too low can result in a read operation stopping early and possibly giving the impression that data loss occurred. Setting timeouts too high usually is not a problem, especially when a separate thread is handling the receive operation. However, it may become a problem if the receiver thread is also responsible for other operations besides checking the port for incoming data. With a little experimentation, you can determine whether or not the class's default behavior of disabling read timeouts and setting the write timeout to one second is sufficient for your needs.
I = Interval ms
T = Total ms (Multiplier * Bytes_Requested) + Constant
Interval Total Behavior
--------------------------------------------------------------------------------
MAXDWORD 0 No read timeouts. Return immediately with any available data.
MAXDWORD * Special case. If the interval and multiplier values are both set
to MAXDWORD, and the constant is set to any non-zero value less
than MAXDWORD, one of the following occurs:
If there are any characters in the input buffer, return
immediately with those characters.
If there are no characters in the input buffer, wait until a
character arrives and then return immediately.
If no character arrives within the time specified by the
constant value, a timeout occurs.
0 0 Return only when the buffer is completely filled. Timeouts are
not used.
0 T Returns when the buffer is completely filled or when T
milliseconds have elapsed since the beginning of the operation.
I 0 Returns when the buffer is completely filled or when I
milliseconds have elapsed between the receipt of any two
characters. Timing does not begin until the first character is
received.
I T Returns when the buffer is completely filled or when either type
of timeout occurs.
Table 3: Behavior of Read Timeout Value Combinations
Conclusion
This article and the example code cover the most common uses for the CSerialPort class.
Instead of covering the remaining member functions in detail, I refer you to the appropriate Win32 online
documentation provided with the compilers. The wrapper functions are identical in name and form except for the
omitted handle parameter that the class manages internally. One final point worth mentioning is that the wrapper
functions will keep track of any error code resulting from the call. The inline member function
CSerialPort::GetLastError will return the proper error value even if your application has called
other Win32 functions that alter what the API-level ::GetLastError returns.
To date, I have used CSerialPort to communicate with other PCs and modems as well as with
hand-held data collection devices and cash registers. It is a versatile class in its own right and provides a
solid foundation from which to build specialized serial communication classes. By letting CSerialPort
handle the underlying details it also makes the transition from the 16-bit to the 32-bit platform a much easier
task.
Last Updated Thursday, August 22, 2013
Send mail to Eric@EWoodruff.us