Spec-Zone.ru › Qt 6.1

Класс QMqttClient

Класс QMqttClient представляет собой центральный доступ для связи с брокером MQTT. Подробнее...

Заголовок: #include <QMqttClient>
qmake: QT += mqtt
Наследует: QObject
  • Список всех членов, включая наследуемые

Открытые типы

Перечисление Ошибка клиента { Нет ошибки, Неверная версия протокола, Идентификатор отклонен, Сервер недоступен, Неверные имя пользователя или пароль, …, Ошибка, специфичная для MQTT 5 }
Перечисление Состояние клиента { Отключено, Подключение, Подключено }
Перечисление Версия протокола { MQTT_3_1, MQTT_3_1_1, MQTT_5_0 }
Перечисление Тип транспорта { IODevice, AbstractSocket, SecureSocket }

Свойства

  • autoKeepAlive : bool
  • cleanSession : bool
  • clientId : QString
  • error : ClientError
  • hostname : QString
  • keepAlive : quint16
  • password : QString
  • port : quint16
  • protocolVersion : ProtocolVersion
  • state : ClientState
  • username : QString
  • willMessage : QByteArray
  • willQoS : quint8
  • willRetain : bool
  • willTopic : QString

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

virtual ~QMqttClient() override
void authenticate(const QMqttAuthenticationProperties &prop)
bool autoKeepAlive() const
bool cleanSession() const
QString clientId() const
void connectToHost()
void connectToHostEncrypted(const QSslConfiguration &conf)
QMqttConnectionProperties connectionProperties() const
void disconnectFromHost()
QMqttClient::ClientError error() const
QString hostname() const
quint16 keepAlive() const
QMqttLastWillProperties lastWillProperties() const
QString password() const
quint16 port() const
QMqttClient::ProtocolVersion protocolVersion() const
qint32 publish(const QMqttTopicName &topic, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
qint32 publish(const QMqttTopicName &topic, const QMqttPublishProperties &properties, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
bool requestPing()
QMqttServerConnectionProperties serverConnectionProperties() const
void setConnectionProperties(const QMqttConnectionProperties &prop)
void setLastWillProperties(const QMqttLastWillProperties &prop)
void setTransport(QIODevice *device, QMqttClient::TransportType transport)
QMqttClient::ClientState state() const
QMqttSubscription * subscribe(const QMqttTopicFilter &topic, quint8 qos = 0)
QMqttSubscription * subscribe(const QMqttTopicFilter &topic, const QMqttSubscriptionProperties &properties, quint8 qos = 0)
QIODevice * transport() const
void unsubscribe(const QMqttTopicFilter &topic)
void unsubscribe(const QMqttTopicFilter &topic, const QMqttUnsubscriptionProperties &properties)
QString username() const
QByteArray willMessage() const
quint8 willQoS() const
bool willRetain() const
QString willTopic() const

Открытые слоты

void setAutoKeepAlive(bool autoKeepAlive)
void setCleanSession(bool cleanSession)
void setClientId(const QString &clientId)
void setError(QMqttClient::ClientError error)
void setHostname(const QString &hostname)
void setKeepAlive(quint16 keepAlive)
void setPassword(const QString &password)
void setPort(quint16 port)
void setProtocolVersion(QMqttClient::ProtocolVersion protocolVersion)
void setState(QMqttClient::ClientState state)
void setUsername(const QString &username)
void setWillMessage(const QByteArray &willMessage)
void setWillQoS(quint8 willQoS)
void setWillRetain(bool willRetain)
void setWillTopic(const QString &willTopic)

Сигналы

void authenticationFinished(const QMqttAuthenticationProperties &p)
void authenticationRequested(const QMqttAuthenticationProperties &p)
void autoKeepAliveChanged(bool autoKeepAlive)
void brokerSessionRestored()
void cleanSessionChanged(bool cleanSession)
void clientIdChanged(QString clientId)
void connected()
void disconnected()
void errorChanged(QMqttClient::ClientError error)
void hostnameChanged(QString hostname)
void keepAliveChanged(quint16 keepAlive)
void messageReceived(const QByteArray &message, const QMqttTopicName &topic = QMqttTopicName())
void messageSent(qint32 id)
void messageStatusChanged(qint32 id, QMqtt::MessageStatus s, const QMqttMessageStatusProperties &properties)
void passwordChanged(QString password)
void pingResponseReceived()
void portChanged(quint16 port)
void protocolVersionChanged(QMqttClient::ProtocolVersion protocolVersion)
void stateChanged(QMqttClient::ClientState state)
void usernameChanged(QString username)
void willMessageChanged(QByteArray willMessage)
void willQoSChanged(quint8 willQoS)
void willRetainChanged(bool willRetain)
void willTopicChanged(QString willTopic)

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

Клиент MQTT — это программа или устройство, использующее MQTT для создания сетевого соединения с сервером MQTT, также называемым брокером. Запрос на подключение должен содержать уникальный идентификатор клиента. По желанию, он может содержать тему Will Topic, сообщение Will Message, имя пользователя и пароль.

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

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

перечисление QMqttClient::ClientError

Это перечисление определяет состояние ошибки клиента.

Постоянная Значение Описание
QMqttClient::NoError 0 Ошибка не произошла.
QMqttClient::InvalidProtocolVersion 1 Брокер не принимает соединение с указанной версией протокола.
QMqttClient::IdRejected 2 Идентификатор клиента имеет неправильный формат. Это может быть связано с его длиной.
QMqttClient::ServerUnavailable 3 Сетевое подключение установлено, но служба недоступна на стороне брокера.
QMqttClient::BadUsernameOrPassword 4 Данные в имени пользователя или пароле имеют неправильный формат.
QMqttClient::NotAuthorized 5 Клиент не авторизован для подключения.
QMqttClient::TransportInvalid 256 Подлежащий транспорт вызвал ошибку. Например, соединение могло быть прервано неожиданно.
QMqttClient::ProtocolViolation 257 Клиент обнаружил нарушение протокола и поэтому закрыл соединение.
QMqttClient::UnknownError 258 Произошла неизвестная ошибка.
QMqttClient::Mqtt5SpecificError 259 Ошибка связана с уровнем 5 протокола MQTT. Код причины может предоставить более подробную информацию.

перечисление QMqttClient::ClientState

Это перечисление определяет состояния, в которые может войти клиент.

Константа Значение Описание
QMqttClient::Disconnected 0 Клиент отключен от брокера.
QMqttClient::Connecting 1 Запрос на подключение был сделан, но брокер еще не одобрил подключение.
QMqttClient::Connected 2 Клиент подключен к брокеру.

enum QMqttClient::ProtocolVersion

Этот перечисление определяет версию протокола MQTT, используемого во время связи с брокером.

Константа Значение Описание
QMqttClient::MQTT_3_1 3 MQTT Стандарт 3.1
QMqttClient::MQTT_3_1_1 4 MQTT Стандарт 3.1.1, публично известный как версия 4
QMqttClient::MQTT_5_0 5 MQTT Стандарт 5.0

enum QMqttClient::TransportType

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

Константа Значение Описание
QMqttClient::IODevice 0 Транспорт использует класс, основанный на QIODevice.
QMqttClient::AbstractSocket 1 Транспорт использует класс, основанный на QAbstractSocket.
QMqttClient::SecureSocket 2 Транспорт использует класс, основанный на QSslSocket.

Свойства

[since 5.14] autoKeepAlive : bool

Это свойство определяет, будет ли клиент автоматически управлять сообщениями keep alive на сервер.

Если это свойство имеет значение true, то клиент будет автоматически отправлять сообщение ping на сервер с интервалом keepAlive.

В противном случае пользователь должен будет вручную вызвать requestPing в течение указанного интервала соединения. Если ping не был отправлен в течение интервала, сервер разорвет соединение.

Значение этого свойства по умолчанию — true.

Это свойство было добавлено в Qt 5.14.

Функции доступа:

bool autoKeepAlive() const
void setAutoKeepAlive(bool autoKeepAlive)

Сигнал уведомления:

void autoKeepAliveChanged(bool autoKeepAlive)

См. также keepAlive(), requestPing(), serverConnectionProperties(), и pingResponseReceived().

cleanSession : bool

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

Функции доступа:

bool cleanSession() const
void setCleanSession(bool cleanSession)

Сигнал уведомления:

void cleanSessionChanged(bool cleanSession)

clientId : QString

Это свойство хранит идентификатор клиента.

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

Функции доступа:

QString clientId() const
void setClientId(const QString &clientId)

Сигнал уведомления:

void clientIdChanged(QString clientId)

error : ClientError

Указывает текущую ошибку клиента.

Функции доступа:

QMqttClient::ClientError error() const
void setError(QMqttClient::ClientError error)

Сигнал уведомления:

void errorChanged(QMqttClient::ClientError error)

hostname : QString

Это свойство хранит имя хоста MQTT-брокера для подключения.

Если транспорт не указан через setTransport(), клиент сам создаст сокетное соединение с указанным именем хоста.

Функции доступа:

QString hostname() const
void setHostname(const QString &hostname)

Сигнал уведомления:

void hostnameChanged(QString hostname)

keepAlive : quint16

Это свойство хранит интервал, с которым отправляются регулярные сообщения ping на брокер.

После установления соединения с брокером клиент должен отправлять частые обновления, чтобы показать, что он все еще доступен. Интервал между этими обновлениями задается этим свойством.

Интервал указывается в секундах.

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

Функции доступа:

quint16 keepAlive() const
void setKeepAlive(quint16 keepAlive)

Сигнал уведомления:

void keepAliveChanged(quint16 keepAlive)

См. также autoKeepAlive(), requestPing(), и pingResponseReceived().

password : QString

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

Функции доступа:

QString password() const
void setPassword(const QString &password)

Сигнал уведомления:

void passwordChanged(QString password)

port : quint16

Это свойство хранит порт для подключения к MQTT-брокеру.

Если транспорт не указан через setTransport(), клиент сам создаст сокетное соединение с хостом по этому номеру порта.

Функции доступа:

quint16 port() const
void setPort(quint16 port)

Сигнал уведомления:

void portChanged(quint16 port)

protocolVersion : ProtocolVersion

Это свойство хранит версию стандарта MQTT, используемую для соединений.

Указывает версию стандарта, которую клиент использует для подключения к брокеру. Допустимые значения:

  • 3: версия стандарта MQTT 3.1.
  • 4: версия стандарта MQTT 3.1.1, часто называемая MQTT 4.

Функции доступа:

QMqttClient::ProtocolVersion protocolVersion() const
void setProtocolVersion(QMqttClient::ProtocolVersion protocolVersion)

Сигнал уведомления:

void protocolVersionChanged(QMqttClient::ProtocolVersion protocolVersion)

state : ClientState

Это свойство хранит текущее состояние клиента.

Функции доступа:

QMqttClient::ClientState state() const
void setState(QMqttClient::ClientState state)

Сигнал уведомления:

void stateChanged(QMqttClient::ClientState state)

username : QString

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

Функции доступа:

QString username() const
void setUsername(const QString &username)

Сигнал уведомления:

void usernameChanged(QString username)

willMessage : QByteArray

Это свойство содержит полезную нагрузку сообщения Will.

Функции доступа:

QByteArray willMessage() const
void setWillMessage(const QByteArray &willMessage)

Сигнал уведомления:

void willMessageChanged(QByteArray willMessage)

willQoS : quint8

Это свойство содержит уровень QoS для отправки и хранения сообщения Will.

Функции доступа:

quint8 willQoS() const
void setWillQoS(quint8 willQoS)

Сигнал уведомления:

void willQoSChanged(quint8 willQoS)

willRetain : bool

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

Функции доступа:

bool willRetain() const
void setWillRetain(bool willRetain)

Сигнал уведомления:

void willRetainChanged(bool willRetain)

willTopic : QString

Это свойство содержит тему Will.

Функции доступа:

QString willTopic() const
void setWillTopic(const QString &willTopic)

Сигнал уведомления:

void willTopicChanged(QString willTopic)

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

[signal, since 5.12] void QMqttClient::authenticationFinished(const QMqttAuthenticationProperties &p)

Этот сигнал испускается после завершения расширенной аутентификации. p указывает доступные детали процесса аутентификации.

После успешной аутентификации испускается QMqttClient::connected.

Примечание: Расширенная аутентификация является частью стандарта MQTT 5.0 и может использоваться только тогда, когда клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

См. также authenticationRequested() и authenticate().

[signal, since 5.12] void QMqttClient::authenticationRequested(const QMqttAuthenticationProperties &p)

Этот сигнал испускается после вызова клиентом QMqttClient::connectToHost или QMqttClient::connectToHostEncrypted и до установления соединения. При расширенной аутентификации брокер может запросить дополнительную информацию, которую необходимо предоставить, вызвав QMqttClient::authenticate. p указывает свойства, предоставленные брокером.

Примечание: Расширенная аутентификация является частью стандарта MQTT 5.0 и может использоваться только тогда, когда клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

См. также authenticationFinished() и authenticate().

[signal] void QMqttClient::brokerSessionRestored()

Этот сигнал испускается после успешного подключения клиента к брокеру со свойством cleanSession установленным в false, и брокер восстановил сессию.

Сессии могут быть восстановлены, если клиент ранее подключался с тем же clientId.

[signal] void QMqttClient::connected()

Этот сигнал испускается при установлении соединения.

[signal] void QMqttClient::disconnected()

Этот сигнал испускается при закрытии соединения. Соединение может быть закрыто при вызове disconnectFromHost() или при разрыве соединения брокером.

[signal] void QMqttClient::messageReceived(const QByteArray &message, const QMqttTopicName &topic = QMqttTopicName())

Этот сигнал испускается при получении нового сообщения. Категория сообщения задаётся topic, а содержимое – message.

[signal] void QMqttClient::messageSent(qint32 id)

Указывает, что сообщение, отправленное через функцию publish(), было получено брокером. id совпадает с тем, что возвращает publish(), чтобы помочь отслеживать статус сообщения.

[signal, since 5.12] void QMqttClient::messageStatusChanged(qint32 id, QMqtt::MessageStatus s, const QMqttMessageStatusProperties &properties)

Этот сигнал испускается при изменении статуса сообщения с идентификатором id. s указывает новый статус сообщения, а properties – дополнительные свойства, предоставленные сервером.

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

[signal] void QMqttClient::pingResponseReceived()

Этот сигнал испускается после ответа брокера на вызов requestPing() или сообщение пинга keepAlive(), и соединение по-прежнему валидно.

[override virtual] QMqttClient::~QMqttClient()

Удаляет клиент MQTT. Если клиент MQTT ещё не отключен от MQTT-брокера, он будет отключен автоматически.

[since 5.12] void QMqttClient::authenticate(const QMqttAuthenticationProperties &prop)

Отправляет запрос на аутентификацию на брокер. prop указывает необходимую информацию для выполнения запроса на аутентификацию.

Эта функция должна вызываться только после испускания сигнала QMqttClient::authenticationRequested.

Примечание: Расширенная аутентификация является частью стандарта MQTT 5.0 и может использоваться только тогда, когда клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

См. также authenticationRequested() и authenticationFinished().

[invokable] void QMqttClient::connectToHost()

Инициализирует подключение к MQTT-брокеру.

Примечание: Эту функцию можно вызвать через систему метаобъектов и из QML. См. Q_INVOKABLE.

[since 5.14] void QMqttClient::connectToHostEncrypted(const QSslConfiguration &conf)

Инициализирует зашифрованное подключение к MQTT-брокеру.

conf задаёт SSL-конфигурацию, которая будет использоваться для подключения.

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

[since 5.12] QMqttConnectionProperties QMqttClient::connectionProperties() const

Возвращает свойства соединения, запрашиваемые клиентом у брокера.

Примечание: QMqttConnectionProperties может использоваться только при указании MQTT_5_0 в качестве ProtocolVersion.

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

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

[invokable] void QMqttClient::disconnectFromHost()

Отключает соединение с брокером MQTT.

Примечание: Эту функцию можно вызывать через систему метаобъектов и из QML. См. Q_INVOKABLE.

[since 5.12] QMqttLastWillProperties QMqttClient::lastWillProperties() const

Возвращает свойства последнего сообщения.

Примечание: QMqttLastWillProperties можно использовать только в случае, если клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

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

[invokable] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)

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

Если retain установлено в true, сообщение останется в броке на случай подключения других клиентов, которые могут получить это сообщение.

Возвращает идентификатор, используемый внутри для идентификации сообщения.

Примечание: Эту функцию можно вызывать через систему метаобъектов и из QML. См. Q_INVOKABLE.

[invokable, since 5.12] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QMqttPublishProperties &properties, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)

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

Если retain установлено в true, сообщение останется в броке на случай подключения других клиентов, которые могут получить это сообщение.

Возвращает идентификатор, используемый внутри для идентификации сообщения.

Примечание: properties будут переданы брокером только при указании клиентом MQTT_5_0 в качестве ProtocolVersion.

Примечание: Эту функцию можно вызывать через систему метаобъектов и из QML. См. Q_INVOKABLE.

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

bool QMqttClient::requestPing()

Отправляет сообщение ping в брокер и ожидает ответа.

Если соединение активно и autoKeepAlive равно true, вызов этой функции завершится ошибкой, так как клиент отвечает за управление этим процессом.

Использование requestPing() вручную требует вызова каждый раз в пределах интервала keepAlive, пока соединение активно.

Чтобы проверить, успешно ли отправлен ping, подключитесь к сигналу pingResponseReceived().

Возвращает true, если запрос ping был отправлен.

См. также pingResponseReceived(), autoKeepAlive() и keepAlive().

[since 5.12] QMqttServerConnectionProperties QMqttClient::serverConnectionProperties() const

Возвращает QMqttServerConnectionProperties, которые брокер вернул после попытки подключения.

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

Примечание: QMqttServerConnectionProperties можно использовать только в случае, если клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

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

[since 5.12] void QMqttClient::setConnectionProperties(const QMqttConnectionProperties &prop)

Устанавливает свойства соединения в prop. QMqttConnectionProperties могут быть использованы для запроса использования определенного набора функций. После запроса подключения ответ сервера можно получить, вызвав QMqttClient::serverConnectionProperties.

Примечание: Свойства соединения можно установить только если клиент находится в состоянии Disconnected.

Примечание: QMqttConnectionProperties можно использовать только в случае, если клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

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

[since 5.12] void QMqttClient::setLastWillProperties(const QMqttLastWillProperties &prop)

Устанавливает свойства последнего сообщения в prop. QMqttLastWillProperties позволяет задавать дополнительные функции для сообщения последнего желания, хранящегося в броке.

Примечание: Свойства соединения можно установить только если клиент находится в состоянии Disconnected.

Примечание: QMqttLastWillProperties можно использовать только в случае, если клиент указывает MQTT_5_0 в качестве ProtocolVersion.

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

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

void QMqttClient::setTransport(QIODevice *device, QMqttClient::TransportType transport)

Устанавливает транспорт в device. Транспорт может быть типа сокета или производным от QIODevice и задается параметром transport.

Примечание: Транспорт можно изменить только если MQTT клиент находится в состоянии Disconnected.

Примечание: Установка пользовательского транспорта для клиента не передает ответственность за управление подключением. Транспорт должен быть открыт для транспортов на основе QIODevice или подключен для транспортов типа сокета перед вызовом QMqttClient::connectToHost().

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

QMqttSubscription *QMqttClient::subscribe(const QMqttTopicFilter &topic, quint8 qos = 0)

Добавляет новую подписку для получения уведомлений по теме topic. Параметр qos определяет уровень, на котором получаются сообщения безопасности. Для получения дополнительной информации о доступных уровнях QoS, см. Качество обслуживания.

Эта функция возвращает указатель на QMqttSubscription. Если одна и та же тема подписана дважды, значение возврата указывает на тот же экземпляр подписки. MQTT клиент является владельцем подписки.

[since 5.12] QMqttSubscription *QMqttClient::subscribe(const QMqttTopicFilter &topic, const QMqttSubscriptionProperties &properties, quint8 qos = 0)

Добавляет новую подписку для получения уведомлений по теме topic. Параметр properties указывает дополнительные свойства подписки, которые будут проверены брокером. Параметр qos определяет уровень, на котором получаются сообщения безопасности. Для получения дополнительной информации о доступных уровнях QoS, см. Качество обслуживания.

Эта функция возвращает указатель на QMqttSubscription. Если одна и та же тема подписана дважды, значение возврата указывает на тот же экземпляр подписки. MQTT клиент является владельцем подписки.

Примечание: properties будут переданы брокером только при указании клиентом MQTT_5_0 в качестве ProtocolVersion.

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

QIODevice *QMqttClient::transport() const

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

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

void QMqttClient::unsubscribe(const QMqttTopicFilter &topic)

Отписывается от темы. Уведомления не будут отправляться ни одной из подписок, сделанных с помощью вызова subscribe().

Примечание: Если клиент отключается от брокера, не отписавшись, брокер сохранит все сообщения и опубликует их при следующей повторной установке соединения.

[since 5.12] void QMqttClient::unsubscribe(const QMqttTopicFilter &topic, const QMqttUnsubscriptionProperties &properties)

Отписывается от темы. Уведомления не будут отправляться ни одной из подписок, сделанных с помощью вызова subscribe(). properties указывает дополнительные пользовательские свойства, которые необходимо передать брокеру.

Примечание: properties будут переданы брокеру только в том случае, если клиент укажет MQTT_5_0 как ProtocolVersion.

Примечание: Если клиент отключается от брокера, не отписавшись, брокер сохранит все сообщения и опубликует их при следующей повторной установке соединения.

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

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.1/qmqttclient.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API