Share via


Configuring a Serial Port

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

Windows Mobile SupportedWindows Embedded CE Supported

8/28/2008

The most critical phase in serial communications programming is configuring the port settings with the DCB structure.

Erroneously initializing the DCB structure is a common problem. When a serial communications function does not produce the expected results, check that the DCB structure is configured correctly.

A call to the CreateFile function opens a serial port with default port settings. Usually, the application needs to change the defaults. Use the GetCommState function to retrieve the default settings and use the SetCommState function to make port settings.

Also, port configuration involves using the COMMTIMEOUTS structure to set the timeout values for read/write operations. When a timeout occurs, the ReadFile or WriteFile function returns the specific number of characters successfully transferred. For additional information on configuring timeouts, see Configuring Timeouts.

To configure a serial port:

  1. Initialize the DCBlength member of the DCB structure to the size of the structure.

    This is required before passing the structure as an argument to a function.

  2. Call the GetCommState function to retrieve the default settings for the port opened with the CreateFile function.

    To identify the port, specify in the hPort parameter the handle that CreateFile returns.

  3. Modify DCB members as required.

    The following are DCB structure members.

    Member Description

    DCBlength

    Before calling the GetCommState function, set this member to the length of the DCB structure.

    Neglecting to do this can cause a failure or return erroneous data.

    BaudRate

    Specifies the device communication rate.

    Assigns an actual baud rate or an index by specifying a CBR_ constant. The CBR_ constants are defined in the winbase.h header file.

    fBinary

    Specifies if binary mode is enabled.

    The Microsoft® Win32® API does not support nonbinary mode transfers, so this member must be TRUE.

    Using FALSE does not work.

    fParity

    Specifies if parity checking is enabled.

    If this member is TRUE, parity checking is performed and errors are reported.

    fOutxCtsFlow

    Turns the CTS flow control on and off.

    To use RTS/CTS flow control, specify TRUE for this member and RTS_CONTROL_HANDSHAKE for the fRtsControl member.

    fOutxDsrFlow

    Turns the DSR flow control on and off.

    DSR flow control is rarely used.

    A typical port configuration is to set this member to FALSE, while enabling the DTR line.

    fDtrControl

    Specifies the DTR flow control.

    DTR_CONTROL_ENABLE turns on the DTR line during the connection.

    DTR_CONTROL_HANDSHAKE turns on DTR handshaking.

    DTR_CONTROL_DISABLE turns off the DTR line.

    fDsrSensitivity

    Specifies if the communications driver is sensitive to the state of the DSR signal.

    If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.

    fTXContinueOnXoff

    Specifies if transmission stops when the input buffer is full and the driver has transmitted the XoffChar character.

    If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes.

    If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.

    fOutX

    Specifies if XON/XOFF flow control is used during transmission.

    If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.

    fInX

    Specifies if XON/XOFF flow control is used during reception.

    If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.

    fErrorChar

    Specifies if bytes received with parity errors are replaced with the character specified by the ErrorChar member.

    If this member is TRUE and the fParity member is TRUE, replacement occurs.

    fNull

    Specifies if null bytes are discarded.

    If this member is TRUE, null bytes are discarded when received.

    fRtsControl

    Turns the RTS flow control on and off.

    RTS_CONTROL_ENABLE turns on the RTS line during the connection.

    RTS_CONTROL_HANDSHAKE turns on RTS handshaking.

    RTS_CONTROL_DISABLE turns off the RTS line.

    RTS_CONTROL_TOGGLE Specifies that the RTS line is high if bytes are available for transmission.

    After all buffered bytes have been sent, the RTS line is low.

    fAbortOnError

    Specifies if read and write operations are terminated when an error occurs.

    If this member is TRUE, the driver terminates read and write operations with an error status when an error occurs.

    The driver does not accept further communications operations until the application has acknowledged the error by calling the ClearCommError function.

    fDummy2

    Reserved; do not use.

    wReserved

    Not used; set to zero.

    XonLim

    Specifies the maximum number of bytes allowed in the queue.

    The XON character is sent if the number of bytes in the queue falls below this number.

    XoffLim

    Specifies the maximum number of bytes accepted in the input buffer before the XOFF character is sent.

    The maximum number of bytes accepted is calculated by subtracting this value from the size, in bytes, of the input buffer.

    ByteSize

    Specifies the bits per byte transmitted and received.

    Parity

    Specifies the parity scheme.

    Do not confuse this member with the fParity member, which turns parity on or off.

    Because parity is rarely used, this member can usually be NOPARITY.

    StopBits

    Specifies the number of stop bits.

    ONESTOPBIT is the most common setting.

    XonChar

    Specifies the value of the XON character for both transmission and reception.

    XoffChar

    Specifies the value of the XOFF character for both transmission and reception.

    ErrorChar

    Specifies the value of the character used to replace bytes received with a parity error.

    EofChar

    Specifies the value of the character used to signal the end of data.

    EvtChar

    Specifies the value of the character used to signal an event.

    WReserved1

    Reserved, do not use.

  4. Call the SetCommState function to set the port settings.

The following code example shows how to use the GetCommState and SetCommState functions to configure a serial port.

DCB PortDCB;

// Initialize the DCBlength member. 
PortDCB.DCBlength = sizeof (DCB); 

// Get the default port setting information.
GetCommState (hPort, &PortDCB);

// Change the DCB structure settings.
PortDCB.BaudRate = 9600;              // Current baud 
PortDCB.fBinary = TRUE;               // Binary mode; no EOF check 
PortDCB.fParity = TRUE;               // Enable parity checking 
PortDCB.fOutxCtsFlow = FALSE;         // No CTS output flow control 
PortDCB.fOutxDsrFlow = FALSE;         // No DSR output flow control 
PortDCB.fDtrControl = DTR_CONTROL_ENABLE; 
                                      // DTR flow control type 
PortDCB.fDsrSensitivity = FALSE;      // DSR sensitivity 
PortDCB.fTXContinueOnXoff = TRUE;     // XOFF continues Tx 
PortDCB.fOutX = FALSE;                // No XON/XOFF out flow control 
PortDCB.fInX = FALSE;                 // No XON/XOFF in flow control 
PortDCB.fErrorChar = FALSE;           // Disable error replacement 
PortDCB.fNull = FALSE;                // Disable null stripping 
PortDCB.fRtsControl = RTS_CONTROL_ENABLE; 
                                      // RTS flow control 
PortDCB.fAbortOnError = FALSE;        // Do not abort reads/writes on 
                                      // error
PortDCB.ByteSize = 8;                 // Number of bits/byte, 4-8 
PortDCB.Parity = NOPARITY;            // 0-4=no,odd,even,mark,space 
PortDCB.StopBits = ONESTOPBIT;        // 0,1,2 = 1, 1.5, 2 

// Configure the port according to the specifications of the DCB 
// structure.
if (!SetCommState (hPort, &PortDCB))
{
  // Could not configure the serial port.
  dwError = GetLastError ();
  MessageBox (hMainWnd, TEXT("Unable to configure the serial port"), 
              TEXT("Error"), MB_OK);
  return FALSE;
}

See Also

Concepts

Programming Serial Connections