BuildCommDCBAndTimeoutsW function (winbase.h)

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 BuildCommDCBAndTimeoutsW(
  [in]  LPCWSTR        lpDef,
  [out] LPDCB          lpDCB,
  [out] LPCOMMTIMEOUTS lpCommTimeouts
);

Parameters

[in] lpDef

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

[out] lpDCB

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.

[out] lpCommTimeouts

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.

Requirements

See also

BuildCommDCB

COMMTIMEOUTS

Communications Functions

Communications Resources

DCB

GetCommTimeouts

SetCommTimeouts