QSerialPort Class

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;
}

成员函数文档

[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 传递。

另请参阅 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 ；否则返回false 。

另请参阅 readLine()。

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

根据给定的方向（directions ）清空输出或输入缓冲区中的所有字符。这包括清空类内部缓冲区和UART（驱动程序）缓冲区，并终止待处理的读写操作。若成功，返回true ；否则返回false 。

[override virtual] void QSerialPort::close()

重写了：QIODevice::close()。

另请参阅 QIODevice::close()。

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

当帧中的数据位发生变化后，将发出此信号。帧中的新数据位将作为dataBits 传递。

另请参阅 QSerialPort::dataBits 。

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

当线路信号 DTR 的状态（高电平或低电平）发生变化后，会发出此信号。线路信号 DTR 的新状态（高电平或低电平）将作为set 传递。

另请参阅 QSerialPort::dataTerminalReady 。

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

当串行端口发生错误时，会发出此信号。指定的error 描述了发生的错误类型。

另请参阅 QSerialPort::error 。

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

在流控制模式发生变更后，将发出此信号。新的流控制模式将作为flow 传递。

另请参阅 QSerialPort::flowControl 。

bool QSerialPort::flush()

该函数在不阻塞的情况下，将内部写入缓冲区中的数据尽可能多地写入底层串口。如果成功写入任何数据，该函数返回true ；否则返回false 。

调用此函数可将缓冲的数据立即发送至串口。成功写入的字节数取决于操作系统。在大多数情况下，无需调用此函数，因为一旦控制权返回给事件循环，QSerialPort 类将自动开始发送数据。如果没有事件循环，请改用waitForBytesWritten()。

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

QSerialPort::Handle QSerialPort::handle() const

如果平台受支持且串口已打开，则返回原生串口句柄；否则返回-1 。

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

重写了：QIODevice::isSequential() const。

始终返回 `true`。串行端口是一种顺序设备。

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

重写：QIODevice::open （QIODeviceBase::OpenMode 模式）。

使用 OpenModemode 打开串行端口，如果成功则返回true ；否则返回false 并设置一个错误代码，该错误代码可通过调用error() 方法获取。

如果端口已打开，但设置所需端口参数失败，则该方法返回false 并自动关闭端口。

另请参阅 QIODeviceBase::OpenMode 和setPort()。

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

在奇偶校验模式发生变更后，将发出此信号。新的奇偶校验模式作为parity 参数传递。

另请参阅 QSerialPort::parity 。

QSerialPort::PinoutSignals QSerialPort::pinoutSignals()

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

根据该结果，可以通过应用“与（AND）”掩码来获取所需信号的状态，其中掩码是来自QSerialPort::PinoutSignals 中的目标枚举值。

另请参阅 QSerialPort::dataTerminalReady 和QSerialPort::requestToSend 。

QString QSerialPort::portName() const

返回由setPort()设置或传递给QSerialPort 构造函数的名称。该名称是简短的，即从设备的内部变量系统位置中提取并转换而来的。转换算法因平台而异：

另请参阅 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 传递。

另请参阅 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 表示写入缓冲区不受限制，传递给write()的所有数据都将被缓冲。这是默认行为。

传递负值的效果与传递0 相同。

该函数在 Qt 6.10 中引入。

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

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

当settingsRestoredOnClose 属性发生更改后，将触发此信号。restore 参数包含该属性的新值。

该函数在 Qt 6.9 中引入。

另请参阅 QSerialPort::settingsRestoredOnClose 。

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

当帧中的停止位数发生变化后，将发出此信号。帧中新的停止位数将作为stopBits 传递。

另请参阅 QSerialPort::stopBits 。

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

重写自：QIODevice::waitForBytesWritten(int msecs)。

该函数将阻塞，直到至少有一个字节被写入串行端口且触发了bytesWritten()信号。该函数将在msecs 毫秒后超时；默认超时时间为30000毫秒。若msecs 为-1，则该函数不会超时。

如果触发了bytesWritten() 信号，该函数将返回true ；否则，将返回false （表示发生错误或操作超时）。

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

重写自：QIODevice::waitForReadyRead(int msecs)。

该函数将阻塞，直到有新数据可供读取且已发出readyRead()信号为止。该函数将在msecs 毫秒后超时；默认超时时间为30000毫秒。如果msecs 为-1，则该函数不会超时。

如果触发了readyRead() 信号且有新数据可供读取，该函数将返回true ；否则将返回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)。