PySide6.QtMqtt.QMqttClient

class QMqttClient

QMqttClient 类表示与 MQTT 代理通信的中心访问。更多…

PySide6.QtMqtt.QMqttClient 的继承图

概要

属性

  • autoKeepAliveᅟ - 此属性决定客户端是否会自动管理向服务器发送的保持连接消息

  • cleanSessionᅟ - 此属性保存连接到代理后的状态

  • clientIdᅟ - 此属性保存客户端的标识符值

  • errorᅟ - 指定客户端的当前错误

  • hostnameᅟ - 此属性保存要连接的MQTT代理的主机名

  • keepAliveᅟ - 此属性保存定期向代理发送ping消息的间隔时间

  • passwordᅟ - 此属性保存用于连接到代理的密码

  • portᅟ - 此属性保存连接到MQTT代理的端口

  • protocolVersionᅟ - 此属性保存用于连接的MQTT标准版本

  • stateᅟ - 此属性保存客户端的当前状态

  • usernameᅟ - 此属性保存用于连接到代理的用户名

  • willMessageᅟ - 此属性保存Will Message的有效载荷

  • willQoSᅟ - 此属性用于设置发送和存储遗嘱消息的服务质量等级

  • willRetainᅟ - 此属性决定是否应在代理上保留Will消息，以便未来的订阅者可以接收

  • willTopicᅟ - 此属性保存遗嘱主题

方法

插槽

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

MQTT客户端是一个使用MQTT创建与MQTT服务器（也称为代理）的网络连接的程序或设备。连接请求必须包含唯一的客户端标识符。可选地，它可以包含遗嘱主题、遗嘱消息、用户名和密码。

一旦创建了连接，客户端可以发送其他客户端可能感兴趣接收的消息，订阅以请求主题的通知，取消订阅以移除通知请求，并从代理断开连接。

class TransportType

此枚举类型指定用于实例化与代理的连接的方法。

常量

描述

QMqttClient.IODevice

传输使用基于QIODevice的类。

QMqttClient.AbstractSocket

传输使用基于QAbstractSocket的类。

QMqttClient.SecureSocket

传输使用基于QSslSocket的类。
class ClientState

此枚举类型指定客户端可以进入的状态。

常量

描述

QMqttClient.Disconnected

客户端已从代理断开连接。

QMqttClient.Connecting

已发出连接请求，但代理尚未批准连接。

QMqttClient.Connected

客户端已连接到代理。
class ClientError

此枚举类型指定客户端的错误状态。

常量

描述

QMqttClient.NoError

没有发生错误。

QMqttClient.InvalidProtocolVersion

代理不接受使用指定协议版本的连接。

QMqttClient.IdRejected

客户端ID格式不正确。这可能与其长度有关。

QMqttClient.ServerUnavailable

网络连接已建立，但代理端的服务不可用。

QMqttClient.BadUsernameOrPassword

用户名或密码中的数据格式不正确。

QMqttClient.NotAuthorized

客户端未被授权连接。

QMqttClient.TransportInvalid

底层传输导致了一个错误。例如，连接可能意外中断。

QMqttClient.ProtocolViolation

客户端遇到协议违规，因此关闭了连接。

QMqttClient.UnknownError

发生了一个未知错误。

QMqttClient.Mqtt5SpecificError

该错误与MQTT协议级别5相关。原因代码可能提供更多详细信息。
class ProtocolVersion

此枚举指定在与代理通信期间使用的MQTT标准的协议版本。

常量

描述

QMqttClient.MQTT_3_1

MQTT 标准 3.1

QMqttClient.MQTT_3_1_1

MQTT标准3.1.1，通常称为版本4

QMqttClient.MQTT_5_0

MQTT 标准 5.0

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property autoKeepAliveᅟ: bool

此属性表示客户端是否会自动管理向服务器发送的保持活动消息。

如果此属性为true，则客户端将在keepAlive间隔内自动向服务器发送ping消息。

否则，用户将必须在连接的指定间隔内手动调用requestPing。如果在间隔内没有发送ping，服务器将断开连接。

此属性的默认值为true。

Access functions:
property cleanSessionᅟ: bool

此属性保存连接到代理后的状态。

Access functions:
property clientIdᅟ: str

此属性保存此属性保存客户端的标识符值。

每个客户端都需要有一个唯一的ID才能连接到MQTT代理。如果用户没有指定客户端ID，则在建立连接时将自动生成一个。

Access functions:
property errorᅟ: QMqttClient.ClientError

此属性指定客户端的当前错误。

Access functions:
property hostnameᅟ: str

此属性保存要连接的MQTT代理的主机名。

如果没有通过setTransport()指定传输方式，客户端将自行实例化一个到指定主机名的套接字连接。

Access functions:
property keepAliveᅟ: int

此属性保存此属性保存向代理发送常规ping消息的间隔。

一旦与代理的连接建立，客户端需要频繁发送更新以传播它仍然可以到达。这些更新之间的间隔由此属性指定。

间隔以秒为单位指定。

如果代理在宽限期内没有响应，连接将被关闭。

Access functions:
property passwordᅟ: str

此属性保存用于连接到代理的密码。

Access functions:
property portᅟ: int

此属性保存连接到MQTT代理的端口。

如果没有通过setTransport()指定传输方式，客户端将实例化一个与此端口号的主机的套接字连接。

Access functions:
property protocolVersionᅟ: QMqttClient.ProtocolVersion

此属性保存用于连接的MQTT标准版本。

指定客户端用于连接到代理的标准版本。有效值为：

  • 3: MQTT 标准版本 3.1。

  • 4: MQTT标准版本3.1.1，通常称为MQTT 4。

  • 5: MQTT 标准 5.0。

Access functions:
property stateᅟ: QMqttClient.ClientState

此属性保存此属性保存客户端的当前状态。

Access functions:
property usernameᅟ: str

此属性保存用于连接到代理的用户名。

Access functions:
property willMessageᅟ: QByteArray

此属性保存此属性保存Will Message的有效负载。

Access functions:
property willQoSᅟ: int

此属性保存此属性保存发送和存储遗嘱消息的服务质量（QoS）级别。

Access functions:
property willRetainᅟ: bool

此属性表示此属性表示是否应将遗嘱消息保留在代理上，以便未来的订阅者接收。

Access functions:
property willTopicᅟ: str

此属性保存此属性保存Will Topic。

Access functions:
__init__([parent=None])
Parameters:

父对象 – QObject

创建一个具有指定parent的新MQTT客户端实例。

authenticate(prop)
Parameters:

prop – QMqttAuthenticationProperties

向代理发送认证请求。prop 指定了完成认证请求所需的必要信息。

此函数仅在发出authenticationRequested信号后调用。

注意

扩展认证是MQTT 5.0标准的一部分，只有在客户端指定MQTT_5_0作为ProtocolVersion时才能使用。

另请参阅

authenticationRequested() authenticationFinished()

authenticationFinished(p)
Parameters:

p – QMqttAuthenticationProperties

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

成功认证后，connected 被触发。

注意

扩展认证是MQTT 5.0标准的一部分，只有在客户端指定MQTT_5_0作为ProtocolVersion时才能使用。

另请参阅

authenticationRequested() authenticate()

authenticationRequested(p)
Parameters:

p – QMqttAuthenticationProperties

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

注意

扩展认证是MQTT 5.0标准的一部分，只有在客户端指定MQTT_5_0作为ProtocolVersion时才能使用。

另请参阅

authenticationFinished() authenticate()

autoKeepAlive()
Return type:

布尔

另请参阅

setAutoKeepAlive()

属性 autoKeepAliveᅟ 的获取器。

autoKeepAliveChanged(autoKeepAlive)
Parameters:

autoKeepAlive – 布尔值

属性 autoKeepAliveᅟ 的通知信号。

brokerSessionRestored()

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

如果客户端之前使用相同的 clientId 连接过，会话可以被恢复。

cleanSession()
Return type:

布尔

另请参阅

setCleanSession()

属性 cleanSessionᅟ 的获取器。

cleanSessionChanged(cleanSession)
Parameters:

cleanSession – 布尔值

属性 cleanSessionᅟ 的通知信号。

clientId()
Return type:

字符串

另请参阅

setClientId()

属性 clientIdᅟ 的获取器。

clientIdChanged(clientId)
Parameters:

clientId – str

属性 clientIdᅟ 的通知信号。

connectToHost()

启动与MQTT代理的连接。

connectToHostEncrypted(conf)
Parameters:

conf – QSslConfiguration

启动与MQTT代理的加密连接。

conf 指定用于连接的SSL配置

connected()

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

connectionProperties()
Return type:

QMqttConnectionProperties

返回客户端请求到代理的连接属性。

注意

QMqttConnectionProperties 只能在客户端指定 MQTT_5_0 作为 ProtocolVersion 时使用。

另请参阅

setConnectionProperties()

disconnectFromHost()

断开与MQTT代理的连接。

disconnected()

当连接关闭时，会发出此信号。当调用disconnectFromHost()或代理断开连接时，连接可能会关闭。

error()
Return type:

ClientError

另请参阅

setError()

属性 errorᅟ 的获取器。

errorChanged(error)
Parameters:

错误 – ClientError

属性 errorᅟ 的通知信号。

hostname()
Return type:

字符串

另请参阅

setHostname()

属性 hostnameᅟ 的获取器。

hostnameChanged(hostname)
Parameters:

主机名 – str

属性 hostnameᅟ 的通知信号。

keepAlive()
Return type:

整数

另请参阅

setKeepAlive()

属性 keepAliveᅟ 的获取器。

keepAliveChanged(keepAlive)
Parameters:

keepAlive – int

属性 keepAliveᅟ 的通知信号。

lastWillProperties()
Return type:

QMqttLastWillProperties

返回最后的遗嘱属性。

注意

QMqttLastWillProperties 只能在客户端指定 MQTT_5_0 作为 ProtocolVersion 时使用。

另请参阅

setLastWillProperties()

messageReceived(message[, topic=QMqttTopicName()])
Parameters:

当接收到新消息时，会发出此信号。消息的类别由topic指定，内容为message。

messageSent(id)
Parameters:

id – int

表示通过publish()函数发送的消息已被代理接收。id与publish()返回的相同，以帮助跟踪消息的状态。

messageStatusChanged(id, s, properties)
Parameters:

当由id标识的消息状态发生变化时，会发出此信号。s指定消息的新状态，properties指定服务器提供的附加属性。

password()
Return type:

字符串

另请参阅

setPassword()

属性 passwordᅟ 的获取器。

passwordChanged(password)
Parameters:

password – str

属性 passwordᅟ 的通知信号。

pingResponseReceived()

此信号在代理响应requestPing()调用或keepAlive()心跳消息后发出，且连接仍然有效。

port()
Return type:

整数

另请参阅

setPort()

属性 portᅟ 的获取器。

portChanged(port)
Parameters:

端口 – int

属性 portᅟ 的通知信号。

protocolVersion()
Return type:

ProtocolVersion

另请参阅

setProtocolVersion()

属性 protocolVersionᅟ 的获取器。

protocolVersionChanged(protocolVersion)
Parameters:

protocolVersion – ProtocolVersion

属性 protocolVersionᅟ 的通知信号。

publish(topic[, message=QByteArray()[, qos=0[, retain=false]]])
Parameters:
Return type:

整数

向指定的topic发布message到代理。qos指定了传输消息所需的QoS级别。

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

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

publish(topic, properties[, message=QByteArray()[, qos=0[, retain=false]]])
Parameters:
Return type:

整数

向代理发布一个带有指定properties和topic的message。qos指定了传输消息所需的QoS级别。

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

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

注意

properties 只有在客户端指定 MQTT_5_0 作为 ProtocolVersion 时才会传递给代理。

requestPing()
Return type:

布尔

向代理发送一个ping消息并期待回复。

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

手动使用requestPing()需要在连接处于活动状态时，在keepAlive间隔内每次调用。

要检查ping是否成功，请连接到pingResponseReceived()信号。

如果ping请求可以发送，则返回true。

serverConnectionProperties()
Return type:

QMqttServerConnectionProperties

返回代理在连接尝试后返回的QMqttServerConnectionProperties。

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

注意

QMqttServerConnectionProperties 只能在客户端指定 MQTT_5_0 作为 ProtocolVersion 时使用。

另请参阅

connectionProperties()

setAutoKeepAlive(autoKeepAlive)
Parameters:

autoKeepAlive – 布尔值

另请参阅

autoKeepAlive()

属性 autoKeepAliveᅟ 的设置器。

setCleanSession(cleanSession)
Parameters:

cleanSession – 布尔值

另请参阅

cleanSession()

属性 cleanSessionᅟ 的设置器。

setClientId(clientId)
Parameters:

clientId – str

另请参阅

clientId()

属性 clientIdᅟ 的设置器。

setConnectionProperties(prop)
Parameters:

prop – QMqttConnectionProperties

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

注意

只有在MQTT客户端处于Disconnected状态时，才能设置连接属性。

注意

QMqttConnectionProperties 只能在客户端指定 MQTT_5_0 作为 ProtocolVersion 时使用。

另请参阅

connectionProperties()

setError(error)
Parameters:

错误 – ClientError

另请参阅

error()

属性 errorᅟ 的设置器。

setHostname(hostname)
Parameters:

主机名 – str

另请参阅

hostname()

属性 hostnameᅟ 的设置器。

setKeepAlive(keepAlive)
Parameters:

keepAlive – int

另请参阅

keepAlive()

属性 keepAliveᅟ 的设置器。

setLastWillProperties(prop)
Parameters:

prop – QMqttLastWillProperties

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

注意

只有在MQTT客户端处于Disconnected状态时，才能设置连接属性。

注意

QMqttLastWillProperties 只能在客户端指定 MQTT_5_0 作为 ProtocolVersion 时使用。

另请参阅

lastWillProperties()

setPassword(password)
Parameters:

password – str

另请参阅

password()

属性 passwordᅟ 的设置器。

setPort(port)
Parameters:

端口 – int

另请参阅

port()

属性 portᅟ 的设置器。

setProtocolVersion(protocolVersion)
Parameters:

protocolVersion – ProtocolVersion

另请参阅

protocolVersion()

属性 protocolVersionᅟ 的设置器。

setState(state)
Parameters:

状态 – ClientState

另请参阅

state()

属性 stateᅟ 的设置器。

setTransport(device, transport)
Parameters:

将传输设置为device。传输可以是套接字类型或从QIODevice派生，并由transport指定。

注意

只有在MQTT客户端处于Disconnected状态时，才能交换传输。

注意

为客户端设置自定义传输并不会转移连接管理的责任。在调用connectToHost()之前，必须为基于QIODevice的传输打开传输，或为套接字类型的传输连接。

另请参阅

transport()

setUsername(username)
Parameters:

username – str

另请参阅

username()

属性 usernameᅟ 的设置器。

setWillMessage(willMessage)
Parameters:

willMessage – QByteArray

另请参阅

willMessage()

属性 willMessageᅟ 的设置器。

setWillQoS(willQoS)
Parameters:

willQoS – int

另请参阅

willQoS()

属性 willQoSᅟ 的设置器。

setWillRetain(willRetain)
Parameters:

willRetain – 布尔值

另请参阅

willRetain()

属性 willRetainᅟ 的设置器。

setWillTopic(willTopic)
Parameters:

willTopic – str

另请参阅

willTopic()

属性 willTopicᅟ 的设置器。

state()
Return type:

ClientState

另请参阅

setState()

属性 stateᅟ 的获取器。

stateChanged(state)
Parameters:

状态 – ClientState

属性 stateᅟ 的通知信号。

subscribe(topic[, qos=0])
Parameters:
Return type:

QMqttSubscription

添加一个新的订阅以接收关于topic的通知。参数qos指定了接收安全消息的级别。有关可用QoS级别的更多信息，请参阅Quality of Service。

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

subscribe(topic, properties[, qos=0])
Parameters:
Return type:

QMqttSubscription

添加一个新的订阅以接收关于topic的通知。参数properties指定了由代理验证的附加订阅属性。参数qos指定了接收安全消息的级别。有关可用QoS级别的更多信息，请参见Quality of Service。

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

注意

properties 只有在客户端指定 MQTT_5_0 作为 ProtocolVersion 时才会传递给代理。

transport()
Return type:

QIODevice

返回用于与代理通信的传输。

另请参阅

setTransport()

unsubscribe(topic)
Parameters:

主题 – QMqttTopicFilter

取消订阅topic。通过调用subscribe()所做的任何订阅将不会收到通知。

注意

如果客户端在未取消订阅的情况下断开与代理的连接，代理将存储所有消息并在下次重新连接时发布它们。

unsubscribe(topic, properties)
Parameters:

取消订阅topic。通过调用subscribe()所做的任何订阅将不会收到通知。properties指定要传递给代理的额外用户属性。

注意

如果客户端在没有取消订阅的情况下断开与代理的连接，代理将存储所有消息并在下次重新连接时发布它们。

注意

properties 只有在客户端指定 MQTT_5_0 作为 ProtocolVersion 时才会传递给代理。

username()
Return type:

字符串

另请参阅

setUsername()

属性 usernameᅟ 的获取器。

usernameChanged(username)
Parameters:

username – str

属性 usernameᅟ 的通知信号。

willMessage()
Return type:

QByteArray

另请参阅

setWillMessage()

属性 willMessageᅟ 的获取器。

willMessageChanged(willMessage)
Parameters:

willMessage – QByteArray

属性 willMessageᅟ 的通知信号。

willQoS()
Return type:

整数

另请参阅

setWillQoS()

属性 willQoSᅟ 的获取器。

willQoSChanged(willQoS)
Parameters:

willQoS – int

属性 willQoSᅟ 的通知信号。

willRetain()
Return type:

布尔

另请参阅

setWillRetain()

属性 willRetainᅟ 的获取器。

willRetainChanged(willRetain)
Parameters:

willRetain – 布尔值

属性 willRetainᅟ 的通知信号。

willTopic()
Return type:

字符串

另请参阅

setWillTopic()

属性 willTopicᅟ 的获取器。

willTopicChanged(willTopic)
Parameters:

willTopic – str

属性 willTopicᅟ 的通知信号。