Класс QSerialPort

Предоставляет функции для доступа к последовательным портам. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Публичные типы

Свойства

Открытые функции

Переопределённые открытые функции

Сигналы

Переопределенные защищенные функции

Подробное описание

Вы можете получить информацию о доступных последовательных портах, используя вспомогательный класс QSerialPortInfo, который позволяет перечислить все последовательные порты в системе. Это полезно для получения правильного имени последовательного порта, который вы хотите использовать. Вы можете передать объект вспомогательного класса в качестве аргумента методам setPort() или setPortName() для назначения желаемого последовательного устройства.

После настройки порта вы можете открыть его в режиме только для чтения (r/o), только для записи (w/o) или чтения-записи (r/w) с помощью метода открыть().

Используйте метод закрыть() для закрытия порта и отмены операций ввода-вывода.

После успешного открытия QSerialPort пытается определить текущую конфигурацию порта и инициализирует себя. Вы можете переконфигурировать порт до желаемых настроек с помощью методов setBaudRate(), setDataBits(), setParity(), setStopBits() и setFlowControl().

Есть несколько свойств для работы с сигналами вывода, а именно: QSerialPort::dataTerminalReady, QSerialPort::requestToSend. Также можно использовать метод pinoutSignals() для запроса текущих установленных сигналов вывода.

После того, как вы узнаете, что порты готовы к чтению или записи, вы можете использовать методы read() или write(). Кроме того, можно вызвать удобные методы readLine() и readAll(). Если не все данные считываются сразу, оставшиеся данные будут доступны позже, поскольку новые входящие данные добавляются в внутренний буфер чтения QSerialPort. Вы можете ограничить размер буфера чтения с помощью setReadBufferSize().

QSerialPort предоставляет набор функций, которые приостанавливают вызывающий поток до тех пор, пока не будут выпущены определенные сигналы. Эти функции могут быть использованы для реализации блокирующих последовательных портов:

• waitForReadyRead() блокирует вызовы до тех пор, пока не станут доступны новые данные для чтения.
• waitForBytesWritten() блокирует вызовы до тех пор, пока один пакет данных не будет записан в последовательный порт.

Смотрите следующий пример:

int numRead = 0, numReadTotal = 0;
char buffer[50];

for (;;) {
    numRead  = serial.read(buffer, 50);

    // Do whatever with the array

    numReadTotal += numRead;
    if (numRead == 0 && !serial.waitForReadyRead())
        break;
}

Если waitForReadyRead() возвращает false, соединение было закрыто или произошла ошибка.

Если в какой-либо момент произойдет ошибка, QSerialPort выпустит сигнал errorOccurred(). Вы также можете вызвать error() для определения типа произошедшей ошибки.

Программирование с блокирующим последовательным портом радикально отличается от программирования с неблокирующим последовательным портом. Блокирующий последовательный порт не требует цикла событий и, как правило, приводит к более простому коду. Однако в приложении графического интерфейса блокирующий последовательный порт следует использовать только в потоках, не связанных с графическим интерфейсом, чтобы избежать зависания пользовательского интерфейса.

Для получения более подробной информации об этих подходах обратитесь к приложениям примеров.

Класс QSerialPort также может использоваться с QTextStream и QDataStream операторами потоков (operator<<() и operator>>()). Однако следует учитывать одну проблему: убедитесь, что достаточно данных доступно перед попыткой чтения с помощью перегруженного оператора operator>>().

См. также QSerialPortInfo.

Документация по типам членов

перечисление QSerialPort::BaudRate

Это перечисление описывает скорость передачи данных, с которой работает устройство связи.

См. также QSerialPort::baudRate.

перечисление QSerialPort::DataBits

Это перечисление описывает количество битов данных, используемых.

См. также QSerialPort::dataBits.

перечисление QSerialPort::Directionфлаги QSerialPort::Directions

Это перечисление описывает возможные направления передачи данных.

Тип Directions — это псевдоним для QFlags<Direction>. Он хранит сочетание значений Direction с помощью операции ИЛИ.

перечисление QSerialPort::FlowControl

Это перечисление описывает используемый метод управления потоком.

См. также QSerialPort::flowControl.

перечисление QSerialPort::Parity

Это перечисление описывает используемую схему чётности.

См. также QSerialPort::parity.

перечисление QSerialPort::PinoutSignalфлаги QSerialPort::PinoutSignals

Это перечисление описывает возможные сигналы для подключения RS-232.

Тип PinoutSignals является псевдонимом для QFlags<PinoutSignal>. Он хранит логическое ИЛИ комбинацию значений PinoutSignal.

См. также pinoutSignals(), QSerialPort::dataTerminalReady и QSerialPort::requestToSend.

перечисление QSerialPort::SerialPortError

Это перечисление описывает ошибки, которые могут содержаться в свойстве QSerialPort::error.

См. также QSerialPort::error.

перечисление QSerialPort::StopBits

Это перечисление описывает количество стоп-битов.

См. также QSerialPort::stopBits.

Документация функций-членов

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

Создает новый объект последовательного порта с заданным parent для представления последовательного порта с указанным вспомогательным классом serialPortInfo.

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

Создает новый объект последовательного порта с заданным parent для представления последовательного порта со значением name.

Имя должно иметь определенный формат; см. метод setPort().

QSerialPort::QSerialPort(QObject *parent = nullptr)

Создает новый объект последовательного порта с заданным parent.

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

Этот сигнал испускается после изменения скорости передачи данных. Новая скорость передачи данных передается как baudRate, а направления как directions.

Примечание: Сигнал-уведомление для свойства baudRate.

См. также QSerialPort::baudRate.

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

Этот сигнал испускается после изменения размера данных в кадре. Новый размер данных в кадре передается как dataBits.

Примечание: Сигнал-уведомление для свойства dataBits.

См. также QSerialPort::dataBits.

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

Этот сигнал испускается после изменения состояния (высокого или низкого) сигнала линии DTR. Новое состояние (высокое или низкое) сигнала линии DTR передается как set.

Примечание: Сигнал-уведомление для свойства dataTerminalReady.

См. также QSerialPort::dataTerminalReady.

[signal, since 5.8] void QSerialPort::errorOccurred(QSerialPort::SerialPortError error)

Этот сигнал испускается при возникновении ошибки в последовательном порту. Указанная error описывает тип возникшей ошибки.

Примечание: Сигнал-уведомление для свойства error.

Эта функция была представлена в Qt 5.8.

См. также QSerialPort::error.

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

Этот сигнал испускается после изменения режима управления потоком. Новый режим управления потоком передается как flow.

Примечание: Сигнал-уведомление для свойства flowControl.

См. также QSerialPort::flowControl.

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

Этот сигнал испускается после изменения режима проверки чётности. Новый режим проверки чётности передаётся как parity.

Примечание: Сигнал-уведомление для свойства parity.

См. также QSerialPort::parity.

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

Этот сигнал испускается после изменения состояния (высокого или низкого) сигнала линии RTS. Новое состояние (высокое или низкое) сигнала линии RTS передаётся как set.

Примечание: Сигнал-уведомление для свойства requestToSend.

См. также QSerialPort::requestToSend.

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

Этот сигнал испускается после изменения количества стоповых битов в кадре. Новое количество стоповых битов в кадре передаётся как stopBits.

Примечание: Сигнал-уведомление для свойства stopBits.

См. также QSerialPort::stopBits.

[virtual] QSerialPort::~QSerialPort()

Закрывает последовательный порт, если необходимо, а затем уничтожает объект.

[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().

bool QSerialPort::flush()

Эта функция записывает как можно больше данных из внутреннего буфера записи в базовый последовательный порт без блокировки. Если данные были записаны, эта функция возвращает true; в противном случае возвращает false.

Вызывайте эту функцию для немедленной отправки буферизованных данных в последовательный порт. Количество успешно записанных байтов зависит от операционной системы. В большинстве случаев вызывать эту функцию не нужно, так как класс QSerialPort автоматически начнёт отправку данных, как только управление вернётся в цикл событий. При отсутствии цикла событий, используйте waitForBytesWritten().

См. также write() и waitForBytesWritten().

[since 5.2] QSerialPort::Handle QSerialPort::handle() const

Если платформа поддерживается и последовательный порт открыт, возвращает дескриптор native последовательного порта; в противном случае возвращает -1.

Эта функция была представлена в Qt 5.2.

[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().

См. также QIODeviceBase::OpenMode и setPort().

QSerialPort::PinoutSignals QSerialPort::pinoutSignals()

Возвращает состояние сигналов линии в формате битовой карты.

Из этого результата можно получить состояние нужного сигнала, применив маску «И», где маска — желаемое значение перечисления из 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).

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().

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

Реализует: QIODevice::waitForBytesWritten(int msecs).

Эта функция блокируется до тех пор, пока не будет записан хотя бы один байт в последовательный порт и не будет послан сигнал 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().

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

Реализует: QIODevice::writeData(const char *data, qint64 maxSize).