BuildCommDCB

2.x

The BuildCommDCB function translates a device-definition string into appropriate serial device control block (DCB) codes.

Parameters

lpszDef

Points to a null-terminated string that specifies device-control information. The string must have the same form as the parameters used in the MS-DOS mode command.

lpdcb

Points to a DCB structure that will receive the translated string. The structure defines the control settings for the serial-communications device. The DCB structure has the following form:

typedef struct tagDCB        /* dcb                             */
{
    BYTE Id;                 /* internal device identifier      */
    UINT BaudRate;           /* baud rate                       */
    BYTE ByteSize;           /* number of bits/byte, 4-8        */
    BYTE Parity;             /* 0-4=none,odd,even,mark,space    */
    BYTE StopBits;           /* 0,1,2 = 1, 1.5, 2               */
    UINT RlsTimeout;         /* timeout for RLSD to be set      */
    UINT CtsTimeout;         /* timeout for CTS to be set       */
    UINT DsrTimeout;         /* timeout for DSR to be set       */

    UINT fBinary        :1;  /* binary mode (skip EOF check)    */
    UINT fRtsDisable    :1;  /* don't assert RTS at init time   */
    UINT fParity        :1;  /* enable parity checking          */
    UINT fOutxCtsFlow   :1;  /* CTS handshaking on output       */
    UINT fOutxDsrFlow   :1;  /* DSR handshaking on output       */
    UINT fDummy         :2;  /* reserved                        */
    UINT fDtrDisable    :1;  /* don't assert DTR at init time   */

    UINT fOutX          :1;  /* enable output XON/XOFF          */
    UINT fInX           :1;  /* enable input XON/XOFF           */
    UINT fPeChar        :1;  /* enable parity err replacement   */
    UINT fNull          :1;  /* enable null stripping           */
    UINT fChEvt         :1;  /* enable Rx character event       */
    UINT fDtrflow       :1;  /* DTR handshake on input          */
    UINT fRtsflow       :1;  /* RTS handshake on input          */
    UINT fDummy2        :1;


    char XonChar;            /* Tx and Rx XON character         */
    char XoffChar;           /* Tx and Rx XOFF character        */
    UINT XonLim;             /* transmit XON threshold          */
    UINT XoffLim;            /* transmit XOFF threshold         */
    char PeChar;             /* parity error replacement char   */
    char EofChar;            /* end of Input character          */
    char EvtChar;            /* received event character        */
    UINT TxDelay;            /* amount of time between chars    */
} DCB;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

Return Value

The return value is zero if the function is successful. Otherwise, it is –1.

Comments

The BuildCommDCB function only fills the buffer. To apply the settings to a port, an application should use the SetCommState function.

By default, BuildCommDCB specifies XON/XOFF and hardware flow control as disabled. To enable flow control, an application should set the appropriate members in the DCB structure.

Example

The following example uses the BuildCommDCB and SetCommState functions to set up COM1 to operate at 9600 baud, with no parity, 8 data bits, and 1 stop bit:

idComDev = OpenComm("COM1", 1024, 128);
if (idComDev < 0) {
    ShowError(idComDev, "OpenComm");
    return 0;
}

err = BuildCommDCB("COM1:9600,n,8,1", &dcb);
if (err < 0) {
    ShowError(err, "BuildCommDCB");
    return 0;
}

err = SetCommState(&dcb);
if (err < 0) {
    ShowError(err, "SetCommState");
    return 0;
}

See Also

SetCommState