SetCommState function (winbase.h)

Configures a communications device according to the specifications in a device-control block (a DCB structure). The function reinitializes all hardware and control settings, but it does not empty output or input queues.

Syntax

BOOL SetCommState(
  [in] HANDLE hFile,
  [in] LPDCB  lpDCB
);

Parameters

[in] hFile

A handle to the communications device. The CreateFile function returns this handle.

[in] lpDCB

A pointer to a DCB structure that contains the configuration information for the specified communications device.

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 SetCommState function uses a DCB structure to specify the desired configuration. The GetCommState function returns the current configuration.

To set only a few members of the DCB structure, you should modify a DCB structure that has been filled in by a call to GetCommState. This ensures that the other members of the DCB structure have appropriate values.

The SetCommState function fails if the XonChar member of the DCB structure is equal to the XoffChar member.

When SetCommState is used to configure the 8250, the following restrictions apply to the values for the DCB structure's ByteSize and StopBits members:

The number of data bits must be 5 to 8 bits.

Examples

For an example, see Configuring a Communications Resource.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header winbase.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See also

BuildCommDCB

Communications Functions

Communications Resources

CreateFile

DCB

GetCommState