BuildCommDCBAndTimeouts function

Translates a device-definition string into appropriate device-control block codes and places them into a device control block. The function can also set up time-out values, including the possibility of no time-outs, for a device; the function's behavior in this regard depends on the contents of the device-definition string.

Syntax


BOOL WINAPI BuildCommDCBAndTimeouts(
  _In_   LPCTSTR lpDef,
  _Out_  LPDCB lpDCB,
  _Out_  LPCOMMTIMEOUTS lpCommTimeouts
);

Parameters

lpDef [in]

The device-control information. The function takes this string, parses it, and then sets appropriate values in the DCB structure pointed to by lpDCB.

The string must have the same form as the mode command's command-line arguments:

COMx[:][baud={11|110|15|150|30|300|60|600|12|1200|24|2400|48|4800|96|9600|19|19200}][parity={n|e|o|m|s}][data={5|6|7|8}][stop={1|1.5|2}][to={on|off}][xon={on|off}][odsr={on|off}][octs={on|off}][dtr={on|off|hs}][rts={on|off|hs|tg}][idsr={on|off}]

The "baud" substring can be any of the values listed, which are in pairs. The two-digit values are the first two digits of the associated values that they represent. For example, 11 represents 110 baud, 19 represents 19,200 baud.

The "parity" substring indicates how the parity bit is used to detect transmission errors. The values represent "none", "even", "odd", "mark", and "space".

For more information, see the Mode command reference in TechNet.

For example, the following string specifies a baud rate of 1200, no parity, 8 data bits, and 1 stop bit:

baud=1200 parity=N data=8 stop=1

lpDCB [out]

A pointer to a DCB structure that receives information from the device-control information string pointed to by lpDef. This DCB structure defines the control settings for a communications device.

lpCommTimeouts [out]

A pointer to a COMMTIMEOUTS structure that receives time-out information.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The BuildCommDCBAndTimeouts function modifies its time-out setting behavior based on the presence or absence of a "to={on|off}" substring in lpDef:

  • If that string contains the substring "to=on", the function sets the WriteTotalTimeoutConstant member of the COMMTIMEOUTS structure to 60000 and all other members to 0.
  • If that string contains the substring "to=off", the function sets the members of COMMTIMEOUTS to 0.
  • If that string does not specify a "to={on|off}" substring, the function ignores the COMMTIMEOUTS structure in lpCommTimeouts.

For more information, see the Remarks for the BuildCommDCB function.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header

Winbase.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

BuildCommDCBAndTimeoutsW (Unicode) and BuildCommDCBAndTimeoutsA (ANSI)

See also

BuildCommDCB
COMMTIMEOUTS
Communications Functions
Communications Resources
DCB
GetCommTimeouts
SetCommTimeouts

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.