BuildCommDCBAndTimeouts

The 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 varies based on the contents of the device-definition string.

BOOL BuildCommDCBAndTimeouts(
  LPCTSTR lpDef,                  // device-control string
  LPDCB lpDCB,                    // device-control block
  LPCOMMTIMEOUTS  lpCommTimeouts  // device time-out values
);

Parameters

lpDef

[in] Pointer to a null-terminated string that specifies device-control information for the device. The function takes this string, parses it, and then sets appropriate values in the DCB structure pointed to by lpDCB.

lpDCB

[out] 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

[in] Pointer to a COMMTIMEOUTS structure that the function can use to set device time-out values.

The BuildCommDCBAndTimeouts function modifies its time-out setting behavior based on the presence or absence of a "TO=xxx" substring in the string specified by lpDef:

• If that string contains the substring "TO=ON", the function sets up total read and write time-out values for the device based on the time-out structure pointed to by lpCommTimeouts.
• If that string contains the substring "TO=OFF", the function sets up the device with no time-outs.
• If that string contains neither the "TO=ON" substring nor the "TO=OFF" substring, the function ignores the time-out structure pointed to by lpCommTimeouts. The time-out structure will not be accessed.

Return Values

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.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Communications Overview, Communication Functions, BuildCommDCB, COMMTIMEOUTS, DCB, GetCommTimeouts, SetCommTimeouts