Класс QSerialPort

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

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

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

Общедоступные типы

Свойства

• 1 свойство унаследовано от QObject

Общедоступные функции

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

• 43 Общедоступные функции, унаследованные от QIODevice
• 32 Общедоступные функции, унаследованные от QObject

Сигналы

• 6 сигналов, унаследованных от QIODevice
• 2 сигнала, унаследованные от QObject

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

• 5 защищённых функций, унаследованных от QIODevice
• 9 защищённых функций, унаследованных от QObject

Дополнительные унаследованные члены

• 1 общедоступный слот, унаследованный от QObject
• 11 статические общедоступные члены, унаследованные от QObject
• 5 защищённых функций, унаследованных от QIODevice
• 9 защищённых функций, унаследованных от QObject

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

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

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

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

Примечание: Последовательный порт всегда открывается с эксклюзивным доступом (то есть ни один другой процесс или поток не может получить доступ к уже открытому последовательному порту).

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

После успешного открытия 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() для определения типа произошедшей ошибки.

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

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

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

См. также QSerialPortInfo.

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

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

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

Примечание: В этом перечислении указаны только наиболее распространённые стандартные скорости передачи.

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

enum QSerialPort::DataBits

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

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

enum QSerialPort::Directionflags QSerialPort::Directions

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

Примечание: Это перечисление используется для настройки скорости передачи устройства отдельно для каждого направления на некоторых операционных системах (например, похожих на POSIX).

Тип Directions является псевдонимом для QFlags<Direction>. Он хранит комбинацию значений Direction, объединённых операцией ИЛИ.

enum QSerialPort::FlowControl

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

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

enum QSerialPort::Parity

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

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

enum QSerialPort::PinoutSignalflags QSerialPort::PinoutSignals

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

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

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

enum QSerialPort::SerialPortError

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

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

enum QSerialPort::StopBits

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

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

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

QSerialPort::QSerialPort(QObject *parent = nullptr)

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

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

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

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

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

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

[virtual] QSerialPort::~QSerialPort()

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

[virtual] bool QSerialPort::atEnd() const

Переопределено из QIODevice::atEnd().

Возвращает true если больше нет доступных данных для чтения; в противном случае возвращает false.

Эта функция чаще всего используется при чтении данных из последовательного порта в цикле. Например:

// This slot is connected to QSerialPort::readyRead()
void QSerialPortClass::readyReadSlot()
{
    while (!port.atEnd()) {
        QByteArray data = port.read(100);
        ....
    }
}

См. также bytesAvailable() и readyRead().

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

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

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

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

[virtual] qint64 QSerialPort::bytesAvailable() const

Переопределено из QIODevice::bytesAvailable().

Возвращает количество ожидающих чтения входящих байтов.

См. также bytesToWrite() и read().

[virtual] qint64 QSerialPort::bytesToWrite() const

Переопределено из QIODevice::bytesToWrite().

Возвращает количество ожидающих записи байтов. Байты записываются, когда управление возвращается в цикл событий или когда вызывается flush().

См. также bytesAvailable() и flush().

[virtual] bool QSerialPort::canReadLine() const

Переопределено из QIODevice::canReadLine().

Возвращает true если из последовательного порта можно прочитать строку данных; в противном случае возвращает false.

См. также readLine().

bool QSerialPort::clear(Directions directions = AllDirections)

Отбрасывает все символы из буфера вывода или ввода в зависимости от заданных направлений directions. Это включает очистку внутренних буферов класса и буферов UART (драйвера). Также прерывает ожидающие операции чтения или записи. Если успешно, возвращает true; в противном случае возвращает false.

Примечание: Последовательный порт должен быть открыт перед попыткой очистить буферизованные данные; в противном случае возвращает false и устанавливает код ошибки NotOpenError.

[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 описывает тип возникшей ошибки.

Данная функция была добавлена в Qt 5.8.

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

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

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

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

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

bool QSerialPort::flush()

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

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

Примечание: Последовательный порт должен быть открыт перед попыткой сбросить буферизованные данные; в противном случае возвращает false и устанавливает код ошибки NotOpenError.

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

Handle QSerialPort::handle() const

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

Предупреждение: Эта функция предназначена только для опытных пользователей; используйте её на свой страх и риск. Кроме того, эта функция не несёт гарантии совместимости между версиями Qt.

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

[virtual] bool QSerialPort::isSequential() const

Переопределено из QIODevice::isSequential().

Всегда возвращает true. Порт COM является последовательным устройством.

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

Переопределено из QIODevice::open().

Открывает порт COM с использованием флага OpenMode mode и возвращает true в случае успеха; в противном случае возвращает false и устанавливает код ошибки, который можно получить, вызвав метод error().

Примечание: Метод возвращает false при успешном открытии порта, но не удалось установить параметры порта. В этом случае порт автоматически закрывается, чтобы не оставлять порт с неправильными настройками.

Предупреждение: Значение mode должно быть QIODevice::ReadOnly, QIODevice::WriteOnly или QIODevice::ReadWrite. Другие режимы не поддерживаются.

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

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

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

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

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

PinoutSignals QSerialPort::pinoutSignals()

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

По этому результату можно получить состояние нужного сигнала, применив маску «И», где маска — желаемое значение перечисления из QSerialPort::PinoutSignals.

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

Примечание: Порт COM должен быть открыт перед попыткой получить сигналы pinout; в противном случае возвращает NoSignal и устанавливает код ошибки NotOpenError.

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

QString QSerialPort::portName() const

Возвращает имя, установленное методом setPort() или переданное конструктору QSerialPort. Это имя короткое, т.е. оно извлечено и преобразовано из системного расположения устройства. Алгоритм преобразования зависит от платформы:

См. также setPortName(), setPort() и QSerialPortInfo::portName().

qint64 QSerialPort::readBufferSize() const

Возвращает размер внутреннего буфера чтения. Это ограничивает количество данных, которые клиент может получить, прежде чем вызвать методы read() или readAll().

Размер буфера чтения 0 (по умолчанию) означает, что буфер не имеет ограничения по размеру, гарантируя, что данные не будут потеряны.

См. также setReadBufferSize() и read().

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

Переопределено из QIODevice::readData().

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

Переопределено из QIODevice::readLineData().

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

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

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

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

bool QSerialPort::sendBreak(int duration = 0)

Этот метод устарел.

Отправляет непрерывный поток нулевых бит в течение заданного периода времени duration в мс, если терминал использует асинхронные данные последовательного порта. В случае успеха возвращает true; в противном случае возвращает false.

Если duration равно нулю, то нулевые биты передаются в течение не менее 0.25 секунд, но не более 0.5 секунд.

Если duration отлично от нуля, то нулевые биты передаются в течение определённого периода времени, зависящего от реализации.

Примечание: Порт COM должен быть открыт перед попыткой отправить паузу; в противном случае возвращает false и устанавливает код ошибки NotOpenError.

См. также setBreakEnabled().

void QSerialPort::setPort(const QSerialPortInfo &serialPortInfo)

Устанавливает порт, хранящийся в экземпляре QSerialPortInfo serialPortInfo.

См. также portName() и QSerialPortInfo.

void QSerialPort::setPortName(const QString &name)

Устанавливает имя name порта COM.

Имя порта COM может быть передано как короткое имя или полное системное расположение, если необходимо.

См. также portName() и QSerialPortInfo.

void QSerialPort::setReadBufferSize(qint64 size)

Устанавливает размер внутреннего буфера чтения QSerialPort на size байт.

Если размер буфера ограничен, QSerialPort не будет буферизировать больше данных, чем этот размер. Специальный случай размера буфера 0 означает, что буфер чтения не ограничен, и все входящие данные буферизуются. Это значение по умолчанию.

Эта опция полезна, если данные считываются только в определённые моменты времени (например, в приложении реального времени потоковой передачи) или если нужно защитить порт COM от получения слишком большого объёма данных, что может привести к недостатку памяти в приложении.

См. также readBufferSize() и read().

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

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

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

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

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

Переопределено из QIODevice::waitForBytesWritten().

Этот метод блокируется до тех пор, пока не будет записан по крайней мере один байт в порт COM и не будет испущен сигнал bytesWritten(). Метод будет ожидать истечения времени после msecs миллисекунд; значение по умолчанию — 30000 миллисекунд. Если msecs равно -1, этот метод не будет ожидать истечения времени.

Метод возвращает true если сигнал bytesWritten() излучается; в противном случае он возвращает false (если произошла ошибка или операция истекла).

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

Переопределено из QIODevice::waitForReadyRead().

Этот метод блокируется до тех пор, пока новые данные не будут доступны для чтения и не будет испущен сигнал readyRead(). Метод будет ожидать истечения времени после msecs миллисекунд; значение по умолчанию — 30000 миллисекунд. Если msecs равно -1, этот метод не будет ожидать истечения времени.

Метод возвращает true если сигнал readyRead() излучается и доступны новые данные для чтения; в противном случае он возвращает false (если произошла ошибка или операция истекла).

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

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

Переопределено из QIODevice::writeData().