QMqttClient 类
QMqttClient 类表示与 MQTT 代理通信的中心访问点。 更多...
| 头文件 | #include <QMqttClient> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Mqtt) target_link_libraries(mytarget PRIVATE Qt6::Mqtt) |
| qmake | QT += mqtt |
| 继承 | QObject |
公共类型
| 枚举 | ClientError { NoError, InvalidProtocolVersion, IdRejected, ServerUnavailable, BadUsernameOrPassword, …, Mqtt5SpecificError } |
| 枚举 | ClientState { Disconnected, Connecting, Connected } |
| 枚举 | ProtocolVersion { MQTT_3_1, MQTT_3_1_1, MQTT_5_0 } |
| 枚举 | 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 | 端口号() const |
| QMqttClient::协议版本 | 协议版本() const |
| qint32 | 发布(const QMqttTopicName &主题, const QByteArray &消息 = QByteArray(), quint8 服务质量 = 0, bool 保留 = false) |
| qint32 | 发布(const QMqttTopicName &主题, const QMqttPublishProperties &属性, const QByteArray &消息 = QByteArray(), quint8 服务质量 = 0, bool 保留 = false) |
| bool | 请求Ping() |
| QMqttServerConnectionProperties | 服务器连接属性() const |
| void | 设置连接属性(const QMqttConnectionProperties &属性) |
| void | 设置遗嘱属性(const QMqttLastWillProperties &属性) |
| void | 设置传输(QIODevice *设备, QMqttClient::传输类型 传输) |
| QMqttClient::客户端状态 | 状态() const |
| QMqttSubscription * | 订阅(const QMqttTopicFilter &主题, quint8 服务质量 = 0) |
| QMqttSubscription * | 订阅(const QMqttTopicFilter &主题, const QMqttSubscriptionProperties &属性, quint8 服务质量 = 0) |
| QIODevice * | 传输() const |
| void | 退订(const QMqttTopicFilter &主题) |
| void | 退订(const QMqttTopicFilter &主题, const QMqttUnsubscriptionProperties &属性) |
| QString | 用户名() const |
| QByteArray | 遗嘱消息() const |
| quint8 | 遗嘱服务质量() const |
| bool | 遗嘱保留() const |
| QString | 遗嘱主题() const |
公共槽
| void | 自动保持活动状态(bool 自动保持活动状态) |
| void | 清理会话(bool 清理会话) |
| void | 客户端ID(const QString &客户端ID) |
| void | 设置错误(QMqttClient::客户端错误 错误) |
| void | 设置主机名(const QString &主机名) |
| void | 设置存活时间(quint16 存活时间) |
| void | 设置密码(const QString &密码) |
| void | 设置端口号(quint16 端口号) |
| void | 设置协议版本(QMqttClient::协议版本 协议版本) |
| void | 设置状态(QMqttClient::客户端状态 状态) |
| void | 设置用户名(const QString &用户名) |
| void | 设置遗嘱消息(const QByteArray &遗嘱消息) |
| void | 设置遗嘱服务质量(quint8 遗嘱服务质量) |
| void | 设置遗嘱保留(bool 遗嘱保留) |
| void | 设置遗嘱主题(const QString &遗嘱主题) |
信号
| void | 身份验证完成(const QMqttAuthenticationProperties &属性) |
| void | 请求身份验证(const QMqttAuthenticationProperties &属性) |
| void | 自动保持活动状态变化(bool 自动保持活动状态) |
| void | 恢复代理会话() |
| void | 清理会话变化(bool 清理会话) |
| void | 客户端ID变化(QString 客户端ID) |
| void | 连接() |
| void | 断开连接() |
| 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服务器（也称为代理）建立网络连接。连接请求必须包含一个唯一的客户端标识符。可选的，它可以包含遗嘱主题、遗嘱消息、用户名和密码。
一旦建立了连接，客户端可以发送其他客户端可能感兴趣的消息，订阅请求主题的通知，取消订阅以删除通知请求，并与代理断开连接。
成员类型文档
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协议第五级相关。原因代码可能提供更多详细信息。 |
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 |
枚举 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) |
通知器信号
| 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) |
通知器信号
| 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() const |
| void | setProtocolVersion(QMqttClient::ProtocolVersion protocolVersion) |
通知器信号
| void | protocolVersionChanged(QMqttClient::ProtocolVersion protocolVersion) |
state : ClientState
该属性持有客户端的当前状态。
访问函数
| QMqttClient::客户端状态 | 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
该属性持有发送和存储Will消息的QoS级别。
访问函数
| 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) |
成员函数文档
[显式] QMqttClient::QMqttClient(QObject *parent = nullptr)
创建一个具有指定父对象的新MQTT客户端实例。
[重写虚函数 noexcept] QMqttClient::~QMqttClient()
删除MQTT客户端。如果MQTT客户端尚未断开与MQTT代理的连接，则将自动断开连接。
void QMqttClient::authenticate(const QMqttAuthenticationProperties &prop)
向代理发送认证请求。prop指定满足认证请求所需的信息。
此函数只能在发出QMqttClient::authenticationRequested信号后调用。
注意：扩展认证是MQTT 5.0标准的一部分，并且只有当客户端指定MQTT_5_0作为ProtocolVersion时才能使用。
另请参阅：authenticationRequested()和authenticationFinished()。
[信号] void QMqttClient::authenticationFinished(const QMqttAuthenticationProperties &p)
此信号在扩展认证完成后发出。p指定关于认证过程的详细信息。
在认证成功后发出QMqttClient::connected。
注意：扩展认证是MQTT 5.0标准的一部分，并且只有当客户端指定MQTT_5_0作为ProtocolVersion时才能使用。
另请参阅：authenticationRequested()和authenticate()。
[信号] void QMqttClient::authenticationRequested(const QMqttAuthenticationProperties &p)
在客户端调用QMqttClient::connectToHost或QMqttClient::connectToHostEncrypted并建立连接之前发出此信号。在扩展认证中，代理可能会请求更多详细信息，这些详细信息需要通过调用QMqttClient::authenticate来提供。p指定由代理提供的属性。
注意：扩展认证是MQTT 5.0标准的一部分，并且只有当客户端指定MQTT_5_0作为ProtocolVersion时才能使用。
另请参阅：authenticationFinished()和authenticate()。
[信号] void QMqttClient::brokerSessionRestored()
在客户端已经使用相同的clientId连接到代理，并且代理已恢复会话后发出此信号，并且当将cleanSession属性设置为false时。
如果客户端以前使用相同的clientId连接，则可以恢复会话。
[可调用] void QMqttClient::connectToHost()
开始与MQTT代理建立连接。
注意：此函数可以通过元对象系统从QML调用。参见 Q_INVOKABLE。
void QMqttClient::connectToHostEncrypted(const QSslConfiguration &conf)
开始加密与MQTT代理的连接。
conf 指定用于连接的SSL配置
[信号] void QMqttClient::connected()
当连接建立时发出此信号。
QMqttConnectionProperties QMqttClient::connectionProperties() const
返回客户端请求给代理的连接属性。
注意：QMqttConnectionProperties 只能在客户端将 MQTT_5_0 作为 ProtocolVersion 时使用。
也请参阅：setConnectionProperties()。
[可调用] void QMqttClient::disconnectFromHost()
从MQTT代理断开连接。
注意：此函数可以通过元对象系统从QML调用。参见 Q_INVOKABLE。
[信号] void QMqttClient::disconnected()
当连接关闭时发出此信号。连接可能在调用 disconnectFromHost() 或代理断开连接时关闭。
QMqttLastWillProperties QMqttClient::lastWillProperties() const
返回最后的将属性。
注意：QMqttLastWillProperties 只能在客户端将 MQTT_5_0 作为 ProtocolVersion 时使用。
也请参阅：setLastWillProperties()。
[信号] void QMqttClient::messageReceived(const QByteArray &message, const QMqttTopicName &topic = QMqttTopicName())
当收到新消息时发出此信号。消息的类别由 topic 指定，内容为 message。
[信号] void QMqttClient::messageSent(qint32 id)
指示通过 publish() 函数发送的消息已被代理接收。此 id 与 publish() 返回的相同，有助于跟踪消息状态。
[信号] void QMqttClient::messageStatusChanged(qint32 id, QMqtt::MessageStatus s, const QMqttMessageStatusProperties &properties)
当通过 id 识别的消息的状态发生改变时，会发出此信号。 s 指定消息的新状态，而 properties 指定由服务器提供的附加属性。
[signal] void QMqttClient::pingResponseReceived()
在代理对 requestPing() 调用或 keepAlive() ping 消息进行响应后，并且连接仍然有效时，会发出此信号。
[可调用] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
将 消息 发布到指定的 主题。 qos 指定传输消息所需的 QoS 级别。
如果 retain 设置为 true，则消息将保留在代理上，以便其他客户端连接并接收消息。
返回一个 ID，用于内部识别消息。
注意：此函数可以通过元对象系统从QML调用。参见 Q_INVOKABLE。
[可调用] qint32 QMqttClient::publish(const QMqttTopicName &topic, const QMqttPublishProperties &properties, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)
将 消息 发布到具有指定的 属性 和 主题 的代理。 qos 指定传输消息所需的 QoS 级别。
如果 retain 设置为 true，则消息将保留在代理上，以便其他客户端连接并接收消息。
返回一个 ID，用于内部识别消息。
注意： 属性 将仅在客户端指定 MQTT_5_0 作为 ProtocolVersion 时传递到代理。
注意：此函数可以通过元对象系统从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时使用。
void QMqttClient::setConnectionProperties(const QMqttConnectionProperties &prop)
将连接属性设置为prop。可以使用QMqttConnectionProperties请求服务器使用特定的功能集。在连接请求之后，可以通过调用QMqttClient::serverConnectionProperties来获取服务器响应。
注意：只有在MQTT客户端处于Disconnected状态时才能设置连接属性。
注意：QMqttConnectionProperties 只能在客户端将 MQTT_5_0 作为 ProtocolVersion 时使用。
void QMqttClient::setLastWillProperties(const QMqttLastWillProperties &prop)
将最后的遗嘱属性设置为prop。使用QMqttLastWillProperties，可以为存储在代理上的最后的遗嘱消息设置额外的功能。
注意：只有在MQTT客户端处于Disconnected状态时才能设置连接属性。
注意：QMqttLastWillProperties 只能在客户端将 MQTT_5_0 作为 ProtocolVersion 时使用。
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 时传递到代理。
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 时传递到代理。
© 2024 The Qt Company Ltd. 本文档的贡献包含了各自的版权所有者的版权。本文档根据自由软件基金会发布的GNU自由文档许可证版本1.3的条款提供。Qt及其相关标志是芬兰和/或其他国家的The Qt Company Ltd.的商标。所有其他商标均为各自所有者的财产。
