QSerialPort 类

提供访问串口的函数。更多...

头：	`#include <QSerialPort>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS SerialPort)` `target_link_libraries(mytarget PRIVATE Qt6::SerialPort)`
qmake:	`QT += serialport`
继承：	QIODevice

所有成员列表，包括继承成员

注意： 此类的所有函数可重入 .

公共类型

enum	BaudRate { Baud1200, Baud2400, Baud4800, Baud9600, Baud19200, …, Baud115200 }
enum	DataBits { Data5, Data6, Data7, Data8 }
enum	Direction { Input, Output, AllDirections }
flags	Directions
enum	FlowControl { NoFlowControl, HardwareControl, SoftwareControl }
enum	Parity { NoParity, EvenParity, OddParity, SpaceParity, MarkParity }
enum	PinoutSignal { NoSignal, DataTerminalReadySignal, DataCarrierDetectSignal, DataSetReadySignal, RingIndicatorSignal, …, SecondaryReceivedDataSignal }
flags	PinoutSignals
enum	SerialPortError { NoError, DeviceNotFoundError, PermissionError, OpenError, NotOpenError, …, UnknownError }
enum	StopBits { OneStop, OneAndHalfStop, TwoStop }

特性

baudRate : qint32
breakEnabled : bool
dataBits : DataBits
dataTerminalReady : bool
error : SerialPortError

flowControl : FlowControl
parity : Parity
requestToSend : bool
(从 6.9 起) settingsRestoredOnClose : bool
stopBits : StopBits

公共函数

	QSerialPort (QObject * parent = nullptr)
	QSerialPort (const QSerialPortInfo & serialPortInfo , QObject * parent = nullptr)
	QSerialPort (const QString & name , QObject * parent = nullptr)
virtual	~QSerialPort ()
qint32	baudRate (QSerialPort::Directions directions = AllDirections) const
QBindable<QSerialPort::DataBits>	bindableDataBits ()
QBindable<QSerialPort::SerialPortError>	bindableError () const
QBindable<QSerialPort::FlowControl>	bindableFlowControl ()
QBindable<bool>	bindableIsBreakEnabled ()
QBindable<QSerialPort::Parity>	bindableParity ()
QBindable<QSerialPort::StopBits>	bindableStopBits ()
bool	clear (QSerialPort::Directions directions = AllDirections)
void	clearError ()
QSerialPort::DataBits	dataBits () const
QSerialPort::SerialPortError	error () const
QSerialPort::FlowControl	flowControl () const
bool	flush ()
QSerialPort::Handle	handle () const
bool	isBreakEnabled () const
bool	isDataTerminalReady ()
bool	isRequestToSend ()
QSerialPort::Parity	parity () const
QSerialPort::PinoutSignals	pinoutSignals ()
QString	portName () const
qint64	readBufferSize () const
bool	setBaudRate (qint32 baudRate , QSerialPort::Directions directions = AllDirections)
bool	setBreakEnabled (bool set = true)
bool	setDataBits (QSerialPort::DataBits dataBits )
bool	setDataTerminalReady (bool set )
bool	setFlowControl (QSerialPort::FlowControl flowControl )
bool	setParity (QSerialPort::Parity parity )
void	setPort (const QSerialPortInfo & serialPortInfo )
void	setPortName (const QString & name )
void	setReadBufferSize (qint64 size )
bool	setRequestToSend (bool set )
void	setSettingsRestoredOnClose (bool restore )
bool	setStopBits (QSerialPort::StopBits stopBits )
`(从 6.10 起)` void	setWriteBufferSize (qint64 size )
bool	settingsRestoredOnClose () const
QSerialPort::StopBits	stopBits () const
`(从 6.10 起)` qint64	writeBufferSize () const

重实现公共函数

virtual qint64	bytesAvailable () const override
virtual qint64	bytesToWrite () const override
virtual bool	canReadLine () const override
virtual void	close () override
virtual bool	isSequential () const override
virtual bool	open (QIODeviceBase::OpenMode mode ) override
virtual bool	waitForBytesWritten (int msecs = 30000) override
virtual bool	waitForReadyRead (int msecs = 30000) override

信号

void	baudRateChanged (qint32 baudRate , QSerialPort::Directions directions )
void	breakEnabledChanged (bool set )
void	dataBitsChanged (QSerialPort::DataBits dataBits )
void	dataTerminalReadyChanged (bool set )
void	errorOccurred (QSerialPort::SerialPortError error )
void	flowControlChanged (QSerialPort::FlowControl flow )
void	parityChanged (QSerialPort::Parity parity )
void	requestToSendChanged (bool set )
`(从 6.9 起)` void	settingsRestoredOnCloseChanged (bool restore )
void	stopBitsChanged (QSerialPort::StopBits stopBits )

重实现保护函数

virtual qint64	readData (char * data , qint64 maxSize ) override
virtual qint64	readLineData (char * data , qint64 maxSize ) override
virtual qint64	writeData (const char * data , qint64 maxSize ) override

详细描述

可以获取可用串口的有关信息，使用 QSerialPortInfo 帮手类，允许枚举系统中的所有串口。这很有用，为获得要使用的串口的正确名称。可以将帮手类对象作为自变量传递给 setPort () 或 setPortName () 方法来赋值期望的串行设备。

设置后，可以按 r/o (只读)、w/o (只读) 或 r/w (读写) 方式打开端口使用 open () 方法。

注意： 串口的打开是始终采用独占访问 (也就是说，没有其它进程或线程，可以访问已经打开的串口)。

使用 close () 方法关闭端口和取消 I/O 操作。

成功打开后，QSerialPort 会试着确定端口的当前配置并初始化自身。可以重新配置端口到期望设置使用 setBaudRate (), setDataBits (), setParity (), setStopBits ()，和 setFlowControl () 方法。

有几个特性可以工作于引脚信号，也就是： QSerialPort::dataTerminalReady , QSerialPort::requestToSend 。也是可能的，使用 pinoutSignals () 方法以查询当前引脚信号设置。

一旦知道端口读写已就绪，就可以使用 read () 或 write () 方法。另外的 readLine () 和 readAll () 方便方法也可以被援引。若不是一次读取所有数据，稍后将获取剩余数据，因为新传入数据会被追加到 QSerialPort 的内部读取缓冲。可以限制读取缓冲的大小，使用 setReadBufferSize ().

QSerialPort 提供挂起调用线程的一组函数，直到发射某些信号。这些函数可以用于实现阻塞串口：

waitForReadyRead () 阻塞调用，直到有新数据可供读取。
waitForBytesWritten () 阻塞调用，直到某个数据负载被写入串口。

见以下范例：

qint64 numReadTotal = 0;
char buffer[50];
for (;;) {
    const qint64 numRead  = serial.read(buffer, 50);
    // Do whatever with the array
    numReadTotal += numRead;
    if (numRead == 0 && !serial.waitForReadyRead())
        break;
}

若 waitForReadyRead () 返回 false ，连接已关闭 (或出现错误)。

若在任何时间点出现错误，QSerialPort 将发射 errorOccurred () 信号。也可以调用 error () 以查找最后发生的错误类型。

采用阻塞串口编程，完全不同于采用非阻塞串口编程。阻塞串口不要求事件循环，且通常导致更简单代码。不管怎样，在 GUI 应用程序中，阻塞串口只应用于非 GUI 线程，以避免冻结用户界面。

这些方式的更多有关细节，参考范例应用程序。

QSerialPort 类还可以用于 QTextStream and QDataStream 的流运算符 (operator<<() 和 operator>>())。不过，有一个问题要意识到：确保足够的数据可用，先于尝试读取通过使用 operator>>() 重载运算符。

另请参阅 QSerialPortInfo .

成员类型文档编制

enum QSerialPort:: BaudRate

此枚举描述通信设备操作采用的波特率。

注意： 此枚举仅列出最常见标准波特率。

常量	值	描述
`QSerialPort::Baud1200`	`1200`	1200 波特。
`QSerialPort::Baud2400`	`2400`	2400 波特。
`QSerialPort::Baud4800`	`4800`	4800 波特。
`QSerialPort::Baud9600`	`9600`	9600 波特。
`QSerialPort::Baud19200`	`19200`	19200 波特。
`QSerialPort::Baud38400`	`38400`	38400 波特。
`QSerialPort::Baud57600`	`57600`	57600 波特。
`QSerialPort::Baud115200`	`115200`	115200 波特。

另请参阅 QSerialPort::baudRate .

enum QSerialPort:: DataBits

此枚举描述所用的数据位数。

常量	值	描述
`QSerialPort::Data5`	`5`	每个字符的数据位数为 5。用于 Baudot (波特) 码。一般只对旧设备 (譬如：电传打字机) 有意义。
`QSerialPort::Data6`	`6`	每个字符的数据位数为 6。很少使用。
`QSerialPort::Data7`	`7`	每个字符的数据位数为 7。用于真正的 ASCII。一般只对旧设备 (譬如：电传打字机) 有意义。
`QSerialPort::Data8`	`8`	每个字符的数据位数为 8。用于大多数种类的数据，因为这的大小匹配字节大小。它几乎普遍用于较新应用程序。

另请参阅 QSerialPort::dataBits .

enum QSerialPort:: Direction
flags QSerialPort:: Directions

此枚举描述数据传输的可能方向。

注意： 此枚举用于在某些操作系统 (例如：像 POSIX) 为每个方向分别设置设备的波特率。

常量	值	描述
`QSerialPort::Input`	`1`	输入方向。
`QSerialPort::Output`	`2`	输出方向。
`QSerialPort::AllDirections`	`Input \| Output`	同时在 2 方向。

Directions 类型是 typedef 对于 QFlags <Direction>。它存储 Direction 值的 OR 组合。

enum QSerialPort:: FlowControl

此枚举描述所使用的流控制。

常量	值	描述
`QSerialPort::NoFlowControl`	`0`	没有流控制。
`QSerialPort::HardwareControl`	`1`	硬件流控制 (RTS/CTS)。
`QSerialPort::SoftwareControl`	`2`	软件流控制 (XON/XOFF)。

另请参阅 QSerialPort::flowControl .

enum QSerialPort:: Parity

此枚举描述所使用的奇偶校验方案。

常量	值	描述
`QSerialPort::NoParity`	`0`	不发送奇偶校验位。这是最常见的奇偶校验设置。错误检测由通信协议处理。
`QSerialPort::EvenParity`	`2`	每个字符 (包括奇偶校验位) 1 位数始终偶数。
`QSerialPort::OddParity`	`3`	每个字符 (包括奇偶校验位) 1 位数始终奇数。
`QSerialPort::SpaceParity`	`4`	空间奇偶校验。奇偶校验位是在空间信号条件下发送的。它不提供错误检测信息。
`QSerialPort::MarkParity`	`5`	标记奇偶校验。奇偶校验位始终被设为标记信号条件 (逻辑 1)。它不提供错误检测信息。

另请参阅 QSerialPort::parity .

enum QSerialPort:: PinoutSignal
flags QSerialPort:: PinoutSignals

此枚举描述可能的 RS-232 引脚信号。

常量	值	描述
`QSerialPort::NoSignal`	`0x00`	无线路活动
`QSerialPort::DataTerminalReadySignal`	`0x04`	DTR (数据终端就绪)。
`QSerialPort::DataCarrierDetectSignal`	`0x08`	DCD (数据载波检测)。
`QSerialPort::DataSetReadySignal`	`0x10`	DSR (数据集就绪)。
`QSerialPort::RingIndicatorSignal`	`0x20`	RNG (环形指示器)。
`QSerialPort::RequestToSendSignal`	`0x40`	RTS (请求发送)。
`QSerialPort::ClearToSendSignal`	`0x80`	CTS (清零发送)。
`QSerialPort::SecondaryTransmittedDataSignal`	`0x100`	STD (二次传输数据)。
`QSerialPort::SecondaryReceivedDataSignal`	`0x200`	SRD (二次接收数据)。

PinoutSignals 类型是 typedef 对于 QFlags <PinoutSignal>。它存储 PinoutSignal 值的 OR (或) 组合。

另请参阅 pinoutSignals (), QSerialPort::dataTerminalReady ，和 QSerialPort::requestToSend .

enum QSerialPort:: SerialPortError

此枚举描述可能包含的错误通过 QSerialPort::error 特性。

常量	值	描述
`QSerialPort::NoError`	`0`	没有出现错误。
`QSerialPort::DeviceNotFoundError`	`1`	出现错误，当试图打开不存在的设备时。
`QSerialPort::PermissionError`	`2`	出现错误，当试图通过另一进程打开已经打开的设备时 (或用户没有足够权限和证书来打开)。
`QSerialPort::OpenError`	`3`	出现错误，当试图打开在此对象中已经打开的设备时。
`QSerialPort::NotOpenError`	`10`	出现这种错误，当只可以成功履行要执行操作时，若设备是打开的。该值的引入是在 QtSerialPort 5.2.
`QSerialPort::WriteError`	`4`	出现 I/O 错误，当写入数据时。
`QSerialPort::ReadError`	`5`	出现 I/O 错误，当读取数据时。
`QSerialPort::ResourceError`	`6`	出现 I/O 错误，当资源变为不可用时 (如：当从系统意外移除设备时)。
`QSerialPort::UnsupportedOperationError`	`7`	请求的设备操作不支持 (或被在运行操作系统禁止)。
`QSerialPort::TimeoutError`	`9`	出现超时错误。该值的引入是在 QtSerialPort 5.2.
`QSerialPort::UnknownError`	`8`	发生无法识别的错误。

另请参阅 QSerialPort::error .

enum QSerialPort:: StopBits

此枚举描述使用的停止位数。

常量	值	描述
`QSerialPort::OneStop`	`1`	1 停止位。
`QSerialPort::OneAndHalfStop`	`3`	1.5 停止位。这仅用于 Windows 平台。
`QSerialPort::TwoStop`	`2`	2 停止位。

另请参阅 QSerialPort::stopBits .

特性文档编制

baudRate : qint32

此特性保持期望方向的数据波特率

若设置成功 (或在打开端口前有设置)，返回 true ；否则返回 false 并设置错误代码，可以获得通过访问值 QSerialPort::error 特性。要设置波特率，使用枚举 QSerialPort::BaudRate 或任何正 qint32 值。

注意： 若设置是在打开端口前设置的，实际串口设置的自动完成是在 QSerialPort::open () 方法，在那之后，端口打开成功。

警告： 设置 AllDirections 标志在所有平台都支持。Windows 仅支持此模式。

警告： 在 Windows，在任何方向返回相等波特率。

默认值为 Baud9600 (即 9600 比特/秒)。

访问函数：

qint32	baudRate (QSerialPort::Directions directions = AllDirections) const
bool	setBaudRate (qint32 baudRate , QSerialPort::Directions directions = AllDirections)

通知程序信号：

void	baudRateChanged (qint32 baudRate , QSerialPort::Directions directions )

`[bindable]` breakEnabled : bool

注意： 此特性支持 QProperty 绑定。

此特性保持断路时的传输线状态

返回 true 当成功时， false 否则。若标志为 true 那么传输线处于断路状态；否则处于非断路状态。

注意： 串口必须打开，在试着设置 (或获取) 此特性前；否则返回 false 和设置 NotOpenError 错误代码。这有点与众不同，而不是如常规类的 Qt 特性设置。不管怎样，这是特殊用例，由于特性是透过与内核和硬件的交互来设置的。因此，这 2 种情景无法完全相互比较。

访问函数：

bool	isBreakEnabled () const
bool	setBreakEnabled (bool set = true)

通知程序信号：

void	breakEnabledChanged (bool set )

`[bindable]` dataBits : DataBits

注意： 此特性支持 QProperty 绑定。

此特性保持帧中的数据位

若设置成功 (或在打开端口前有设置)，返回 true ；否则返回 false 并设置错误代码，可以获得通过访问值 QSerialPort::error 特性。

注意： 若设置是在打开端口前设置的，实际串口设置的自动完成是在 QSerialPort::open () 方法，在那之后，端口打开成功。

默认值为 Data8 (即：8 数据位)。

访问函数：

QSerialPort::DataBits	dataBits () const
bool	setDataBits (QSerialPort::DataBits dataBits )

通知程序信号：

void	dataBitsChanged (QSerialPort::DataBits dataBits )

dataTerminalReady : bool

此特性保持线路信号 DTR (数据终端就绪) 的状态 (高或低)

返回 true 当成功时， false 否则。若标志为 true 那么 DTR (数据终端就绪) 信号被设为高；否则低。

注意： 串口必须打开，在试着设置 (或获取) 此特性前；否则 false 被返回，且错误代码被设为 NotOpenError .

访问函数：

bool	isDataTerminalReady ()
bool	setDataTerminalReady (bool set )

通知程序信号：

void	dataTerminalReadyChanged (bool set )

另请参阅 pinoutSignals ().

`[bindable read-only]` error : SerialPortError

注意： 此特性支持 QProperty 绑定。

此特性保持串口的错误状态

I/O 设备状态返回错误代码。例如，若 open () 返回 false ，或读/写操作返回 -1 ，此特性可用于弄明白操作为什么失败的原因。

错误代码被设为默认 QSerialPort::NoError 在调用 clearError() 之后

访问函数：

QSerialPort::SerialPortError	error () const
void	clearError ()

通知程序信号：

void	errorOccurred (QSerialPort::SerialPortError error )

`[bindable]` flowControl : FlowControl

注意： 此特性支持 QProperty 绑定。

此属性保存期望的流控制模式

若设置成功 (或在打开端口前有设置)，返回 true ；否则返回 false 并设置错误代码，可以获得通过访问值 QSerialPort::error 特性。

注意： 若设置是在打开端口前设置的，实际串口设置的自动完成是在 QSerialPort::open () 方法，在那之后，端口打开成功。

默认值为 NoFlowControl (即：没有流控制)。

访问函数：

QSerialPort::FlowControl	flowControl () const
bool	setFlowControl (QSerialPort::FlowControl flowControl )

通知程序信号：

void	flowControlChanged (QSerialPort::FlowControl flow )

`[bindable]` parity : Parity

注意： 此特性支持 QProperty 绑定。

此特性保持奇偶校验模式

若设置成功 (或在打开端口前有设置)，返回 true ；否则返回 false 并设置错误代码，可以获得通过访问值 QSerialPort::error 特性。

注意： 若设置是在打开端口前设置的，实际串口设置的自动完成是在 QSerialPort::open () 方法，在那之后，端口打开成功。

默认值为 NoParity (即：没有奇偶校验)。

警告： 某些 UNIX 操作系统 (即 macOS) 不支持 CMSPAR 标志。在这种系统，设置标记或空间奇偶校验不支持。

访问函数：

QSerialPort::Parity	parity () const
bool	setParity (QSerialPort::Parity parity )

通知程序信号：

void	parityChanged (QSerialPort::Parity parity )

requestToSend : bool

此特性保持线路信号 RTS (请求发送) 的状态 (高或低)

返回 true 当成功时， false 否则。若标志为 true 那么 RTS (请求发送) 信号被设为高；否则 low。

注意： 串口必须打开，在试着设置 (或获取) 此特性前；否则 false 被返回，且错误代码被设为 NotOpenError .

注意： 试图控制 RTS (请求发送) 信号在 HardwareControl 模式会失败，具有错误码被设为 UnsupportedOperationError ，因为信号是由驱动程序自动控制的。

访问函数：

bool	isRequestToSend ()
bool	setRequestToSend (bool set )

通知程序信号：

void	requestToSendChanged (bool set )

另请参阅 pinoutSignals ().

`[since 6.9]` settingsRestoredOnClose : bool

此特性定义端口参数，是否应该在关闭时还原

在打开端口后，类会缓存其参数，在应用由用户定义的参数前。

若特性为 true ，串口会试着还原缓存参数，在关闭端口前；否则，丢弃缓存参数。

默认值为 true .

注意： 此特性在某些操作系统中，可能不起作用。例如：macOS 似乎始终还原默认串口设置，当关闭端口时。

该特性在 Qt 6.9 引入。

访问函数：

bool	settingsRestoredOnClose () const
void	setSettingsRestoredOnClose (bool restore )

通知程序信号：

void	settingsRestoredOnCloseChanged (bool restore )

`[bindable]` stopBits : StopBits

注意： 此特性支持 QProperty 绑定。

此特性保持帧中的停止位数

若设置成功 (或在打开端口前有设置)，返回 true ；否则返回 false 并设置错误代码，可以获得通过访问值 QSerialPort::error 特性。

注意： 若设置是在打开端口前设置的，实际串口设置的自动完成是在 QSerialPort::open () 方法，在那之后，端口打开成功。

默认值为 OneStop (即：1 停止位)。

访问函数：

QSerialPort::StopBits	stopBits () const
bool	setStopBits (QSerialPort::StopBits stopBits )

通知程序信号：

void	stopBitsChanged (QSerialPort::StopBits stopBits )

成员函数文档编制

`[explicit]` QSerialPort:: QSerialPort ( QObject * parent = nullptr)

构造新的串口对象采用给定 parent .

`[explicit]` QSerialPort:: QSerialPort (const QSerialPortInfo & serialPortInfo , QObject * parent = nullptr)

构造新的串口对象采用给定 parent 来表示串口采用指定帮手类 serialPortInfo .

`[explicit]` QSerialPort:: QSerialPort (const QString & name , QObject * parent = nullptr)

构造新的串口对象采用给定 parent 来表示串口采用指定的 name .

名称应该有特定格式；见 setPort () 方法。

`[virtual noexcept]` QSerialPort:: ~QSerialPort ()

关闭串口，若有必要，然后销毁对象。

`[signal]` void QSerialPort:: baudRateChanged ( qint32 baudRate , QSerialPort::Directions directions )

此信号发射，在波特率改变后。新波特率被传递作为 baudRate 和方向作为 directions .

注意： 通知程序信号对于特性 baudRate .

另请参阅 QSerialPort::baudRate .

`[override virtual]` qint64 QSerialPort:: bytesAvailable () const

重实现： QIODevice::bytesAvailable () const.

返回等待读取的传入字节数。

另请参阅 bytesToWrite () 和 read ().

`[override virtual]` qint64 QSerialPort:: bytesToWrite () const

重实现： QIODevice::bytesToWrite () const.

返回等待写入的字节数。写入字节当控制回到事件循环或当 flush () 被调用。

另请参阅 bytesAvailable () 和 flush ().

`[override virtual]` bool QSerialPort:: canReadLine () const

重实现： QIODevice::canReadLine () const.

返回 true 若可以从串口读取 1 行数据；否则返回 false .

另请参阅 readLine ().

bool QSerialPort:: clear ( QSerialPort::Directions directions = AllDirections)

丢弃输出 (或输入) 缓冲中的所有字符，从属给定方向 directions 。这包括清零内部类缓冲和 UART (驱动程序) 缓冲。还会终止挂起的读取，或写入操作。若成功，返回 true ；否则返回 false .

注意： 串口必须打开，在试着清零任何缓冲数据前；否则返回 false 和设置 NotOpenError 错误代码。

`[override virtual]` void QSerialPort:: close ()

重实现： QIODevice::close ().

注意： 串口必须打开，在试着关闭它前；否则设置 NotOpenError 错误代码。

另请参阅 QIODevice::close ().

`[signal]` void QSerialPort:: dataBitsChanged ( QSerialPort::DataBits dataBits )

此信号发射，在帧中的数据位改变后。帧中的新数据位被传递作为 dataBits .

注意： 通知程序信号对于特性 dataBits .

另请参阅 QSerialPort::dataBits .

`[signal]` void QSerialPort:: dataTerminalReadyChanged ( bool set )

此信号发射，在线路信号 DTR (数据终端就绪) 状态 (高或低) 改变后。线路信号 DTR 的新状态（高或低）被传递作为 set .

注意： 通知程序信号对于特性 dataTerminalReady .

另请参阅 QSerialPort::dataTerminalReady .

`[signal]` void QSerialPort:: errorOccurred ( QSerialPort::SerialPortError error )

此信号发射，当串口出现错误时。指定的 error 描述出现的错误类型。

注意： 通知程序信号对于特性 error .

另请参阅 QSerialPort::error .

`[signal]` void QSerialPort:: flowControlChanged ( QSerialPort::FlowControl flow )

此信号发射，在流控制模式已改变后。新的流控方式被传递作为 flow .

注意： 通知程序信号对于特性 flowControl .

另请参阅 QSerialPort::flowControl .

bool QSerialPort:: flush ()

此函数尽可能多地把内部写入缓冲，不阻塞写入到底层串口。若有写入任何数据，此函数返回 true ；否则返回 false .

调用此函数把缓冲数据，立即发送给串口。成功写入的字节数，从属 OS (操作系统)。在大多数情况下，不需要调用此函数，因为 QSerialPort 自会开始发送数据，一旦把控制返回给事件循环。若缺乏事件循环，调用 waitForBytesWritten () 代替。

注意： 串口必须打开，在试着刷新任何缓冲数据前；否则返回 false 和设置 NotOpenError 错误代码。

另请参阅 write () 和 waitForBytesWritten ().

QSerialPort::Handle QSerialPort:: handle () const

若平台支持且串口是打开的，返回本机串口句柄；否则返回 -1 .

警告： 此函数仅供专家使用；使用它风险自负。此外，此函数没有携带兼容性承诺，在次要 Qt 发行之间。

`[override virtual]` bool QSerialPort:: isSequential () const

重实现： QIODevice::isSequential () const.

始终返回 true 。串口是顺序设备。

`[override virtual]` bool QSerialPort:: open ( QIODeviceBase::OpenMode mode )

重实现： QIODevice::open (QIODeviceBase::OpenMode mode).

打开串口使用 OpenMode mode ，然后返回 true 若成功；否则返回 false 并设置可以获得的错误代码，通过调用 error () 方法。

若端口被打开，但设置期望的端口参数失败，方法返回 false 并自动关闭端口。

警告： The mode 必须为 QIODeviceBase::ReadOnly , QIODeviceBase::WriteOnly ，或 QIODeviceBase::ReadWrite 。不支持其它模式。

注意： 由于历史原因，当成功打开时 errorOccurred () 信号被发射采用 NoError 错误代码。保留此行为，是为保持向后兼容。

另请参阅 QIODeviceBase::OpenMode and setPort ().

`[signal]` void QSerialPort:: parityChanged ( QSerialPort::Parity parity )

此信号发射，在奇偶校验模式改变后。传递新的奇偶校验模式按 parity .

注意： 通知程序信号对于特性 parity .

另请参阅 QSerialPort::parity .

QSerialPort::PinoutSignals QSerialPort:: pinoutSignals ()

以位图格式返回线路信号的状态。

从此结果，通过应用掩码 AND 来分配期望信号状态是可能的，若掩码是期望的枚举值来自 QSerialPort::PinoutSignals .

注意： 此方法履行系统调用，从而确保正确返回线路信号状态。这是必要的，当底层操作系统无法提供改变有关的适当通知时。

注意： 串口必须打开，在试着获取引脚信号前；否则返回 NoSignal 和设置 NotOpenError 错误代码。

另请参阅 QSerialPort::dataTerminalReady and QSerialPort::requestToSend .

QString QSerialPort:: portName () const

返回的名称设置通过 setPort () 或被传递给 QSerialPort 构造函数。此名称很短 (即：它是从设备的内部变量系统位置提取和转换的)。转换算法平台特定：

平台	简要描述
Windows	移除前缀 \\.\ 或 //./ 从系统位置，并返回剩余字符串。
Unix, BSD	移除前缀 /dev/ 从系统位置，并返回剩余字符串。

另请参阅 setPortName (), setPort ()，和 QSerialPortInfo::portName ().

qint64 QSerialPort:: readBufferSize () const

返回内部读取缓冲的大小。这限制客户端可以接收的数据量，先于调用 read () 或 readAll () 方法。

读取缓冲尺寸为 0 (默认) 意味着缓冲没有大小限制，确保数据不丢失。

另请参阅 setReadBufferSize () 和 read ().

`[override virtual protected]` qint64 QSerialPort:: readData ( char * data , qint64 maxSize )

重实现： QIODevice::readData (char *data, qint64 maxSize).

`[override virtual protected]` qint64 QSerialPort:: readLineData ( char * data , qint64 maxSize )

重实现： QIODevice::readLineData (char *data, qint64 maxSize).

`[signal]` void QSerialPort:: requestToSendChanged ( bool set )

此信号发射，在线路信号 RTS (请求发送) 的状态 (高或低) 已改变后。线路信号 RTS (请求发送) 的新状态 (高或低) 被传递作为 set .

注意： 通知程序信号对于特性 requestToSend .

另请参阅 QSerialPort::requestToSend .

void QSerialPort:: setPort (const QSerialPortInfo & serialPortInfo )

设置端口存储在串口信息实例 serialPortInfo .

另请参阅 portName () 和 QSerialPortInfo .

void QSerialPort:: setPortName (const QString & name )

设置 name 为串口。

串口的名称可以按短名称 (或长系统位置) 传递，若有必要。

另请参阅 portName () 和 QSerialPortInfo .

void QSerialPort:: setReadBufferSize ( qint64 size )

设置大小为 QSerialPort 的内部读取缓冲到 size 字节。

若缓冲尺寸被限制到某个大小， QSerialPort 缓冲数据就不会超过此大小。缓冲大小的特殊情况 0 意味着读取缓冲不受限制，且缓冲所有传入数据。这是默认。

此选项是有用的，若仅在某个时间点读取数据 (例如：在实时流应用程序中)，或者，若应该保护串口，防止接收太多数据 (可能最终导致应用程序内存不足)。

另请参阅 readBufferSize () 和 read ().

`[since 6.10]` void QSerialPort:: setWriteBufferSize ( qint64 size )

设置大小为 QSerialPort 的内部写入缓冲到 size 字节。

通过串口发送数据相对很慢，因此实践中，当 write () 被调用，数据不会被立即发送。它首先存储在中间缓冲，并稍后以组块形式写入。

因此，试图写入太多数据 (或以比底层串口可以处理的更高速率写入数据)，会导致内部缓冲的增长情况。这可能最终导致应用程序内存不足，尤其在低内存资源的设备中。

此方法允许把内部缓冲，限制在某个大小。若下一写入尝试超过缓冲容量， write () 方法将返回实际存储在缓冲中的字节数。重复尝试写入其余字节是用户的责任，后面 bytesWritten () 信号被接收，或后面 waitForBytesWritten () 方法返回 true .

传递 0 给此方法意味着输入缓冲不受限制，并缓冲所有传入数据。这是默认。

该函数在 Qt 6.10 引入。

另请参阅 writeBufferSize () 和 write ().

`[signal, since 6.9]` void QSerialPort:: settingsRestoredOnCloseChanged ( bool restore )

此信号发射后于 settingsRestoredOnClose 特性的改变。 restore 参数包含特性的新值。

注意： 通知程序信号对于特性 settingsRestoredOnClose .

该函数在 Qt 6.9 引入。

另请参阅 QSerialPort::settingsRestoredOnClose .

`[signal]` void QSerialPort:: stopBitsChanged ( QSerialPort::StopBits stopBits )

此信号发射，在帧中的停止位数改变后。新帧的停止位数的传递是按 stopBits .

注意： 通知程序信号对于特性 stopBits .

另请参阅 QSerialPort::stopBits .

`[override virtual]` bool QSerialPort:: waitForBytesWritten ( int msecs = 30000)

重实现： QIODevice::waitForBytesWritten (int msecs).

此函数阻塞，直到至少 1 字节被写入串口和 bytesWritten () 信号已发射。函数将超时后于 msecs 毫秒；默认超时为 30000 毫秒。若 msecs 是 -1，此函数不会超时。

函数返回 true 若 bytesWritten () 信号被发射；否则返回 false (若发生错误或操作超时)。

`[override virtual]` bool QSerialPort:: waitForReadyRead ( int msecs = 30000)

重实现： QIODevice::waitForReadyRead (int msecs).

此函数阻塞，直到有新数据可供读取和 readyRead () 信号已发射。函数将超时后于 msecs 毫秒；默认超时为 30000 毫秒。若 msecs 是 -1，此函数不会超时。

函数返回 true 若 readyRead () 信号被发射且有新的数据可供读取；否则它返回 false (若发生错误或操作超时)。

另请参阅 waitForBytesWritten ().

`[since 6.10]` qint64 QSerialPort:: writeBufferSize () const

返回内部写入缓冲的大小。

写入缓冲大小 0 (默认) 意味着缓冲没有大小限制。

该函数在 Qt 6.10 引入。

另请参阅 setWriteBufferSize () 和 write ().

`[override virtual protected]` qint64 QSerialPort:: writeData (const char * data , qint64 maxSize )

重实现： QIODevice::writeData (const char *data, qint64 maxSize).

QSerialPort 类

公共类型

特性

公共函数

重实现公共函数

信号

重实现保护函数

详细描述

成员类型文档编制

enum QSerialPort:: BaudRate

enum QSerialPort:: DataBits

enum QSerialPort:: Direction flags QSerialPort:: Directions

enum QSerialPort:: FlowControl

enum QSerialPort:: Parity

enum QSerialPort:: PinoutSignal flags QSerialPort:: PinoutSignals

enum QSerialPort:: SerialPortError

enum QSerialPort:: StopBits

特性文档编制

baudRate : qint32

[bindable] breakEnabled : bool

[bindable] dataBits : DataBits

dataTerminalReady : bool

[bindable read-only] error : SerialPortError

[bindable] flowControl : FlowControl

[bindable] parity : Parity

requestToSend : bool

[since 6.9] settingsRestoredOnClose : bool

[bindable] stopBits : StopBits

成员函数文档编制

[explicit] QSerialPort:: QSerialPort ( QObject * parent = nullptr)

[explicit] QSerialPort:: QSerialPort (const QSerialPortInfo & serialPortInfo , QObject * parent = nullptr)

[explicit] QSerialPort:: QSerialPort (const QString & name , QObject * parent = nullptr)

[virtual noexcept] QSerialPort:: ~QSerialPort ()

[signal] void QSerialPort:: baudRateChanged ( qint32 baudRate , QSerialPort::Directions directions )

[override virtual] qint64 QSerialPort:: bytesAvailable () const

[override virtual] qint64 QSerialPort:: bytesToWrite () const

[override virtual] bool QSerialPort:: canReadLine () const

bool QSerialPort:: clear ( QSerialPort::Directions directions = AllDirections)

[override virtual] void QSerialPort:: close ()

[signal] void QSerialPort:: dataBitsChanged ( QSerialPort::DataBits dataBits )

[signal] void QSerialPort:: dataTerminalReadyChanged ( bool set )

[signal] void QSerialPort:: errorOccurred ( QSerialPort::SerialPortError error )

[signal] void QSerialPort:: flowControlChanged ( QSerialPort::FlowControl flow )

bool QSerialPort:: flush ()

QSerialPort::Handle QSerialPort:: handle () const

[override virtual] bool QSerialPort:: isSequential () const

[override virtual] bool QSerialPort:: open ( QIODeviceBase::OpenMode mode )

[signal] void QSerialPort:: parityChanged ( QSerialPort::Parity parity )

QSerialPort::PinoutSignals QSerialPort:: pinoutSignals ()

QString QSerialPort:: portName () const

qint64 QSerialPort:: readBufferSize () const

[override virtual protected] qint64 QSerialPort:: readData ( char * data , qint64 maxSize )

[override virtual protected] qint64 QSerialPort:: readLineData ( char * data , qint64 maxSize )

[signal] void QSerialPort:: requestToSendChanged ( bool set )

void QSerialPort:: setPort (const QSerialPortInfo & serialPortInfo )

void QSerialPort:: setPortName (const QString & name )

void QSerialPort:: setReadBufferSize ( qint64 size )

[since 6.10] void QSerialPort:: setWriteBufferSize ( qint64 size )

[signal, since 6.9] void QSerialPort:: settingsRestoredOnCloseChanged ( bool restore )

[signal] void QSerialPort:: stopBitsChanged ( QSerialPort::StopBits stopBits )

[override virtual] bool QSerialPort:: waitForBytesWritten ( int msecs = 30000)

[override virtual] bool QSerialPort:: waitForReadyRead ( int msecs = 30000)

[since 6.10] qint64 QSerialPort:: writeBufferSize () const

[override virtual protected] qint64 QSerialPort:: writeData (const char * data , qint64 maxSize )

内容

enum QSerialPort:: Direction
flags QSerialPort:: Directions

enum QSerialPort:: PinoutSignal
flags QSerialPort:: PinoutSignals

`[bindable]` breakEnabled : bool

`[bindable]` dataBits : DataBits

`[bindable read-only]` error : SerialPortError

`[bindable]` flowControl : FlowControl

`[bindable]` parity : Parity

`[since 6.9]` settingsRestoredOnClose : bool

`[bindable]` stopBits : StopBits

`[explicit]` QSerialPort:: QSerialPort ( QObject * parent = nullptr)

`[explicit]` QSerialPort:: QSerialPort (const QSerialPortInfo & serialPortInfo , QObject * parent = nullptr)

`[explicit]` QSerialPort:: QSerialPort (const QString & name , QObject * parent = nullptr)

`[virtual noexcept]` QSerialPort:: ~QSerialPort ()

`[signal]` void QSerialPort:: baudRateChanged ( qint32 baudRate , QSerialPort::Directions directions )

`[override virtual]` qint64 QSerialPort:: bytesAvailable () const

`[override virtual]` qint64 QSerialPort:: bytesToWrite () const

`[override virtual]` bool QSerialPort:: canReadLine () const

`[override virtual]` void QSerialPort:: close ()

`[signal]` void QSerialPort:: dataBitsChanged ( QSerialPort::DataBits dataBits )

`[signal]` void QSerialPort:: dataTerminalReadyChanged ( bool set )

`[signal]` void QSerialPort:: errorOccurred ( QSerialPort::SerialPortError error )

`[signal]` void QSerialPort:: flowControlChanged ( QSerialPort::FlowControl flow )

`[override virtual]` bool QSerialPort:: isSequential () const

`[override virtual]` bool QSerialPort:: open ( QIODeviceBase::OpenMode mode )

`[signal]` void QSerialPort:: parityChanged ( QSerialPort::Parity parity )

`[override virtual protected]` qint64 QSerialPort:: readData ( char * data , qint64 maxSize )

`[override virtual protected]` qint64 QSerialPort:: readLineData ( char * data , qint64 maxSize )

`[signal]` void QSerialPort:: requestToSendChanged ( bool set )

`[since 6.10]` void QSerialPort:: setWriteBufferSize ( qint64 size )

`[signal, since 6.9]` void QSerialPort:: settingsRestoredOnCloseChanged ( bool restore )

`[signal]` void QSerialPort:: stopBitsChanged ( QSerialPort::StopBits stopBits )

`[override virtual]` bool QSerialPort:: waitForBytesWritten ( int msecs = 30000)

`[override virtual]` bool QSerialPort:: waitForReadyRead ( int msecs = 30000)

`[since 6.10]` qint64 QSerialPort:: writeBufferSize () const

`[override virtual protected]` qint64 QSerialPort:: writeData (const char * data , qint64 maxSize )