Класс QSerialPort

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

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

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

Типы публичного доступа

Свойства

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

Публичные функции

Переопределенные публичные функции

• 33 публичных функций, унаследованных от QIODevice
• 31 публичных функций, унаследованных от QObject

Сигналы

• 4 сигнала, унаследованные от 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];

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

    // Do whatever with the array

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

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

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

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

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

См. также QSerialPortInfo.

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

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

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

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

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

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

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

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

enum QSerialPort::Directionflags QSerialPort::Directions

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

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

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

enum QSerialPort::FlowControl

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

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

enum QSerialPort::Parity

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

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

enum QSerialPort::PinoutSignalflags QSerialPort::PinoutSignals

Это перечисление описывает возможные сигналы разъёма RS-232.

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

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

enum QSerialPort::SerialPortError

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

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

enum QSerialPort::StopBits

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

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

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

QSerialPort::QSerialPort(QObject *parent = Q_NULLPTR)

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

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

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

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

QSerialPort::QSerialPort(const QSerialPortInfo &serialPortInfo, QObject *parent = Q_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::error(QSerialPort::SerialPortError error)

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

Примечание: Сигнал error перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя функции необходимо указать тип сигнала в static_cast, как показано в этом примере:

connect(serialPort, static_cast<void(QSerialPort::*)(QSerialPort::SerialPortError)>(&QSerialPort::error),
    [=](QSerialPort::SerialPortError error){ /* ... */ });

Примечание: Функция-получатель для свойства error.

См. также 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. Последовательный порт является последовательным устройством.

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

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

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

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

Предупреждение: режим должен быть 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.

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

Примечание: Порт должен быть открыт перед попыткой получения сигналов состояния выводов; в противном случае возвращается 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 не равно нулю, то нулевые биты передаются в течение определенного периода времени в зависимости от реализации.

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

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

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

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

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

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

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

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

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

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

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

Эта функция блокирует выполнение, пока новые данные не станут доступны для чтения и не будет выпущен сигнал readyRead(). Функция будет ожидать в течение msecs миллисекунд.

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

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

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

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