QMqttClient Class

成员函数文档

[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 信号后调用。

另请参阅 authenticationRequested() 和authenticationFinished()。

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

该信号在扩展身份验证完成后发出。p 指定了有关身份验证过程的可用详细信息。

身份验证成功后，将发出QMqttClient::connected 信号。

另请参阅 authenticationRequested() 和authenticate()。

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

该信号在客户端调用QMqttClient::connectToHost 或QMqttClient::connectToHostEncrypted 之后、连接建立之前发出。在扩展身份验证中，代理可能会请求额外的详细信息，需要通过调用QMqttClient::authenticate 来提供这些信息。p 指定了由代理提供的属性。

另请参阅 authenticationFinished() 和authenticate()。

[signal] void QMqttClient::brokerSessionRestored()

当客户端成功连接到代理，且cleanSession 属性设置为false ，同时代理已恢复会话后，将发出此信号。

如果客户端此前曾使用相同的clientId 进行过连接，则可以恢复会话。

[invokable] void QMqttClient::connectToHost()

建立与 MQTT 代理的连接。

void QMqttClient::connectToHostEncrypted(const QSslConfiguration &conf)

与 MQTT 代理建立加密连接。

conf 指定连接时要使用的 SSL 配置

[invokable, since 6.10] void QMqttClient::connectToHostWebSocket(QWebSocket *webSocket = nullptr)

设置 WebSocket 传输类型并向 MQTT 代理发起连接。此操作将替换先前的传输类型。如果指定了webSocket ，则忽略主机名和端口，并使用该 WebSocket 建立连接。webSocket 由调用代码持有，且必须在QMqttClient 对象的生命周期内保持有效。

该函数于 Qt 6.10 中引入。

[invokable, since 6.10] void QMqttClient::connectToHostWebSocketEncrypted(QWebSocket *webSocket = nullptr)

设置安全的 WebSocket 传输类型，并向 MQTT 代理发起连接。此操作将替换之前的传输类型。如果指定了webSocket ，则忽略主机名和端口，并通过该 WebSocket 建立连接。webSocket 由调用代码拥有，且必须在QMqttClient 对象的生命周期内保持有效。

该函数于 Qt 6.10 中引入。

[signal] void QMqttClient::connected()

当连接建立后，会发出此信号。

QMqttConnectionProperties QMqttClient::connectionProperties() const

向经纪商返回客户端请求的连接属性。

另请参阅 setConnectionProperties()。

[invokable] void QMqttClient::disconnectFromHost()

与 MQTT 代理断开连接。

[signal] void QMqttClient::disconnected()

当连接被关闭时，会发出此信号。连接可能在调用disconnectFromHost()时被关闭，也可能在经纪商断开连接时被关闭。

QMqttLastWillProperties QMqttClient::lastWillProperties() const

返回最后一个 will 的属性。

另请参阅 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()探测消息后，且连接仍然有效时，会发出此信号。

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

将message 发布到消息代理，并指定topic 。qos 指定了传输该消息所需的服务质量（QoS）级别。

如果将 `retain ` 设置为 `true`，则该消息将保留在消息代理上，供其他客户端连接并接收该消息。

返回一个用于内部识别该消息的 ID。

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

向消息代理发布一个message ，其中包含指定的properties 和topic 。qos 指定了传输该消息所需的QoS级别。

如果将retain 设置为true ，则该消息将保留在代理上，供其他客户端连接并接收该消息。

返回一个用于内部识别该消息的 ID。

bool QMqttClient::requestPing()

向经纪商发送一个 ping 消息，并等待回复。

如果连接处于活动状态且autoKeepAlive 的值是true ，则调用此函数将失败，因为客户端负责管理此过程。

手动使用 `requestPing() ` 需要只要连接处于活动状态，就必须在 `keepAlive ` 间隔内每次都进行一次调用。

要检查 ping 是否成功，请订阅pingResponseReceived() 信号。

如果能够发送 ping 请求，则返回true 。

另请参阅 pingResponseReceived()、autoKeepAlive() 和keepAlive()。

QMqttServerConnectionProperties QMqttClient::serverConnectionProperties() const

返回经纪商在连接尝试后返回的QMqttServerConnectionProperties 。

这可用于验证由QMqttClient::setConnectionProperties 设置的客户端连接属性是否已被代理接受。此外，在连接尝试失败的情况下，它还可用于连接诊断。

另请参阅 connectionProperties()。

void QMqttClient::setConnectionProperties(const QMqttConnectionProperties &prop)

将连接属性设置为prop 。可通过QMqttConnectionProperties 向服务器请求使用特定的功能集。发送连接请求后，可通过调用QMqttClient::serverConnectionProperties 获取服务器的响应。

另请参阅 connectionProperties()。

void QMqttClient::setLastWillProperties(const QMqttLastWillProperties &prop)

将“最后遗嘱”属性设置为prop 。QMqttLastWillProperties 允许为存储在消息代理中的“最后遗嘱”消息设置附加功能。

另请参阅 lastWillProperties()。

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

将传输设置为device 。传输可以是套接字类型，也可以是从QIODevice 派生而来，并通过transport 进行指定。

另请参阅 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 指定接收安全消息的服务质量级别。有关可用服务质量级别的更多信息，请参阅“服务质量”。

此函数返回一个指向QMqttSubscription 的指针。如果对同一主题进行了两次订阅，则返回值指向同一个订阅实例。MQTT 客户端是该订阅的所有者。

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 指定要传递给消息代理的其他用户属性。