QMqttClient Class
QMqttClient 类代表与 MQTT 代理通信的中心访问。更多
| 头文件： | #include <QMqttClient> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Mqtt)target_link_libraries(mytarget PRIVATE Qt6::Mqtt) |
| qmake： | QT += mqtt |
| 继承： | QObject |
公共类型
| enum | ClientError { NoError, InvalidProtocolVersion, IdRejected, ServerUnavailable, BadUsernameOrPassword, …, Mqtt5SpecificError } |
| enum | ClientState { Disconnected, Connecting, Connected } |
| enum | ProtocolVersion { MQTT_3_1, MQTT_3_1_1, MQTT_5_0 } |
| enum | TransportType { IODevice, AbstractSocket, SecureSocket } |
属性
|
|
公共功能
| QMqttClient(QObject *parent = nullptr) | |
| 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、用户名和密码。
一旦创建了连接，客户端就可以发送其他客户端可能有兴趣接收的消息、订阅以请求主题通知、取消订阅以删除通知请求，以及断开与代理的连接。
成员类型文档
enum QMqttClient::ClientError
该枚举类型指定客户端的错误状态。
| 常量 | 值 | 说明 |
|---|---|---|
QMqttClient::NoError | 0 | 未发生错误。 |
QMqttClient::InvalidProtocolVersion | 1 | 代理不接受使用指定协议版本的连接。 |
QMqttClient::IdRejected | 2 | 客户端 ID 不正确。这可能与其长度有关。 |
QMqttClient::ServerUnavailable | 3 | 网络连接已建立，但代理服务不可用。 |
QMqttClient::BadUsernameOrPassword | 4 | 用户名或密码中的数据畸形。 |
QMqttClient::NotAuthorized | 5 | 客户端无权连接。 |
QMqttClient::TransportInvalid | 256 | 底层传输导致错误。例如，连接可能意外中断。 |
QMqttClient::ProtocolViolation | 257 | 客户端遇到协议违规，因此关闭了连接。 |
QMqttClient::UnknownError | 258 | 发生未知错误。 |
QMqttClient::Mqtt5SpecificError | 259 | 该错误与 MQTT 协议第 5 级有关。原因代码可能会提供更多细节。 |
enum 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 的类。 |
属性文档
autoKeepAlive : bool
此属性表示客户端是否会自动向服务器发送保持存活信息。
如果该属性为true ，则客户端将在keepAlive 间隔自动向服务器发送 ping 消息。
否则，用户必须在指定的连接间隔内手动调用requestPing 。如果在该时间间隔内未发送 ping 信息，服务器将断开连接。
此属性的默认值为true 。
访问功能：
| bool | autoKeepAlive() const |
| void | setAutoKeepAlive(bool autoKeepAlive) |
Notifier 信号：
| void | autoKeepAliveChanged(bool autoKeepAlive) |
另请参阅 keepAlive(),requestPing(),serverConnectionProperties() 和pingResponseReceived().
cleanSession : bool
此属性保存连接到代理后的状态。
访问功能：
| bool | cleanSession() const |
| void | setCleanSession(bool cleanSession) |
通知信号：
| void | cleanSessionChanged(bool cleanSession) |
clientId : QString
该属性包含客户端的标识符值。
每个客户端都需要有一个唯一的 ID 才能连接到 MQTT 代理。如果用户没有指定客户端 ID，则会在建立连接时自动生成一个。
访问功能：
| 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) |
Notifier 信号：
| 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。
- 5：MQTT 标准 5.0。
访问功能：
| 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) |
Notifier 信号：
| void | willMessageChanged(QByteArray willMessage) |
willQoS : quint8
该属性表示发送和存储 Will 报文的 QoS 级别。
访问功能：
| quint8 | willQoS() const |
| void | setWillQoS(quint8 willQoS) |
通知信号：
| void | willQoSChanged(quint8 willQoS) |
willRetain : bool
此属性表示是否应将 Will Message 保留在代理上，供未来订阅者接收。
访问功能：
| bool | willRetain() const |
| void | setWillRetain(bool willRetain) |
Notifier 信号：
| void | willRetainChanged(bool willRetain) |
willTopic : QString
该属性包含 Will Topic。
访问功能：
| QString | willTopic() const |
| void | setWillTopic(const QString &willTopic) |
Notifier 信号：
| void | willTopicChanged(QString willTopic) |
成员函数文档
[explicit] QMqttClient::QMqttClient(QObject *parent = nullptr)
使用指定的parent 创建新的 MQTT 客户端实例。
[override virtual noexcept] QMqttClient::~QMqttClient()
删除 MQTT 客户端。如果 MQTT 客户端尚未断开与 MQTT 代理的连接，则会自动断开。
void QMqttClient::authenticate(const QMqttAuthenticationProperties &prop)
prop 指定满足身份验证请求所需的信息。
该函数只能在QMqttClient::authenticationRequested 信号发出后调用。
注： 扩展身份验证是 MQTT 5.0 标准的一部分，只有当客户端将MQTT_5_0 指定为ProtocolVersion 时才能使用。
另请参阅 authenticationRequested() 和authenticationFinished()。
[signal] void QMqttClient::authenticationFinished(const QMqttAuthenticationProperties &p)
该信号在扩展身份验证完成后发出。p 指明身份验证过程的可用详细信息。
认证成功后，QMqttClient::connected 。
注： 扩展身份验证是 MQTT 5.0 标准的一部分，只有当客户端指定MQTT_5_0 为ProtocolVersion 时才能使用。
另请参阅 authenticationRequested() 和authenticate()。
[signal] void QMqttClient::authenticationRequested(const QMqttAuthenticationProperties &p)
该信号在客户端调用QMqttClient::connectToHost 或QMqttClient::connectToHostEncrypted 之后、连接建立之前发出。在扩展身份验证中，代理可能会要求提供更多细节，这些细节需要通过调用QMqttClient::authenticate 来提供。p 指定代理提供的属性。
注意： 扩展身份验证是 MQTT 5.0 标准的一部分，只有当客户端将MQTT_5_0 指定为ProtocolVersion 时才能使用。
另请参阅 authenticationFinished() 和authenticate()。
[signal] void QMqttClient::brokerSessionRestored()
在客户端成功连接到cleanSession 属性设置为false 的代理，且代理已恢复会话后，会发出该信号。
如果客户端之前使用相同的clientId 进行过连接，则会话可以被恢复。
[invokable] void QMqttClient::connectToHost()
启动与 MQTT 代理的连接。
注： 可通过元对象系统和 QML 调用该函数。请参阅Q_INVOKABLE 。
void QMqttClient::connectToHostEncrypted(const QSslConfiguration &conf)
启动与 MQTT 代理的加密连接。
conf 指定连接使用的 SSL 配置
[signal] void QMqttClient::connected()
连接建立后会发出该信号。
QMqttConnectionProperties QMqttClient::connectionProperties() const
返回客户端向代理请求的连接属性。
注意： QMqttConnectionProperties 只能在客户端将MQTT_5_0 指定为ProtocolVersion 时使用。
另请参阅 setConnectionProperties() 。
[invokable] void QMqttClient::disconnectFromHost()
断开与 MQTT 代理的连接。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[signal] void QMqttClient::disconnected()
连接关闭时发出该信号。连接可能在调用disconnectFromHost() 或代理断开连接时关闭。
QMqttLastWillProperties QMqttClient::lastWillProperties() const
返回最后的意愿属性。
注意： QMqttLastWillProperties 只能在客户端指定MQTT_5_0 为ProtocolVersion 时使用。
另请参阅 setLastWillProperties() 。
[signal] void QMqttClient::messageReceived(const QByteArray &message, const QMqttTopicName &topic = QMqttTopicName())
收到新信息时发出该信号。信息的类别由topic 指定，内容为message 。
[signal] void QMqttClient::messageSent(qint32 id)
表示通过publish() 函数发送的报文已被代理接收。id 与publish() 返回的信息相同，有助于跟踪信息的状态。
[signal] void QMqttClient::messageStatusChanged(qint32 id, QMqtt::MessageStatus s, const QMqttMessageStatusProperties &properties)
id s 指定信息的新状态， 指定服务器提供的附加属性。properties
[signal] void QMqttClient::pingResponseReceived()
该信号在代理响应requestPing() 调用或keepAlive() ping 消息后发出，且连接仍然有效。
[invokable] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
用指定的topic 向代理发布message 。qos 指定传输消息所需的 QoS 级别。
如果retain 设置为true ，则消息将保留在代理上，供其他客户端连接并接收消息。
返回内部用于标识报文的 ID。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[invokable] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QMqttPublishProperties &properties, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
通过指定的properties 和topic 向代理发布message 。qos 指定传输消息所需的 QoS 级别。
如果retain 设置为true ，则消息将留在代理上，供其他客户端连接并接收消息。
返回内部用于标识报文的 ID。
注意： 只有当客户端将MQTT_5_0 指定为ProtocolVersion 时，才会将properties 传递给代理。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
bool QMqttClient::requestPing()
向代理发送 ping 消息并等待回复。
如果连接处于活动状态，且autoKeepAlive 是true ，则调用此函数将失败，因为客户端负责管理此进程。
手动使用requestPing() 时，只要连接处于活动状态，就需要在keepAlive 间隔内每次调用一次。
要检查 ping 是否成功，请连接pingResponseReceived() 信号。
如果可以发送 ping 请求，则返回true 。
另请参阅 pingResponseReceived()、autoKeepAlive() 和keepAlive()。
QMqttServerConnectionProperties QMqttClient::serverConnectionProperties() const
返回代理在尝试连接后返回的QMqttServerConnectionProperties 。
这可用于验证QMqttClient::setConnectionProperties 设置的客户端连接属性是否已被代理接受。此外，在连接尝试失败的情况下，它还可用于连接诊断。
注意： QMqttServerConnectionProperties 只能在客户端将MQTT_5_0 指定为ProtocolVersion 时使用。
另请参阅 connectionProperties() 。
void QMqttClient::setConnectionProperties(const QMqttConnectionProperties &prop)
将连接属性设置为prop 。QMqttConnectionProperties 可用于要求服务器使用特定功能集。发出连接请求后，可通过调用QMqttClient::serverConnectionProperties 获取服务器响应。
注意： 只有当 MQTT 客户端处于Disconnected 状态时，才能设置连接属性。
注意： QMqttConnectionProperties 只能在客户端将MQTT_5_0 指定为ProtocolVersion 时使用。
另请参阅 connectionProperties() 。
void QMqttClient::setLastWillProperties(const QMqttLastWillProperties &prop)
将最后意愿属性设置为prop 。QMqttLastWillProperties 允许为存储在代理处的最后意愿消息设置附加功能。
注意： 只有当 MQTT 客户端处于Disconnected 状态时，才能设置连接属性。
注意： QMqttLastWillProperties 只能在客户端将MQTT_5_0 指定为ProtocolVersion 时使用。
另请参阅 lastWillProperties() 。
void QMqttClient::setTransport(QIODevice *device, QMqttClient::TransportType transport)
将传输设置为device 。传输可以是套接字类型，也可以是从QIODevice 派生的，由transport 指定。
注： 只有当 MQTT 客户端处于Disconnected 状态时，才能交换传输。
注： 为客户端设置自定义传输并不意味着移交连接管理责任。在调用QMqttClient::connectToHost() 之前，必须为基于QIODevice 的传输打开传输，或为套接字类型的传输连接传输。
另请参阅 transport()。
QMqttSubscription *QMqttClient::subscribe(const QMqttTopicFilter &topic, quint8 qos = 0)
添加新订阅以接收topic 上的通知。参数qos 指定接收安全信息的级别。有关可用 QoS 级别的更多信息，请参阅服务质量。
此函数返回一个指向QMqttSubscription 的指针。如果同一主题被订阅两次，返回值将指向同一订阅实例。MQTT 客户端是订阅的所有者。
QMqttSubscription *QMqttClient::subscribe(const QMqttTopicFilter &topic, const QMqttSubscriptionProperties &properties, quint8 qos = 0)
添加新订阅以接收topic 上的通知。参数properties 指定要由代理验证的其他订阅属性。参数qos 指定接收安全信息的级别。有关可用 QoS 级别的更多信息，请参阅服务质量。
此函数返回一个指向QMqttSubscription 的指针。如果同一主题被订阅两次，返回值将指向同一订阅实例。MQTT 客户端是订阅的所有者。
注意： 只有当客户端将MQTT_5_0 指定为ProtocolVersion 时，才会将properties 传递给代理。
QIODevice *QMqttClient::transport() const
返回与经纪人通信时使用的传输方式。
另请参阅 setTransport().
void QMqttClient::unsubscribe(const QMqttTopicFilter &topic)
从topic 取消订阅。将不会向调用subscribe() 的任何订阅发送通知。
注： 如果客户断开与代理的连接而未取消订阅，代理将存储所有消息并在下次重新连接时发布它们。
void QMqttClient::unsubscribe(const QMqttTopicFilter &topic, const QMqttUnsubscriptionProperties &properties)
从topic 取消订阅。调用subscribe() 将不会向任何订阅发送通知。properties 指定了要传递给代理的其他用户属性。
注意： 如果客户断开与代理的连接而未取消订阅，代理将存储所有消息并在下次重新连接时发布它们。
注意： 只有当客户端将MQTT_5_0 指定为ProtocolVersion 时，才会将properties 传递给代理。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
