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.
Note
The winbase.h header defines BuildCommDCBAndTimeouts as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP |
| Minimum supported server | Windows Server 2003 |
| Target Platform | Windows |
| Header | winbase.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |