class QMqttClient#

The QMqttClient class represents the central access communicating with an MQTT broker. More…

Inheritance diagram of PySide6.QtMqtt.QMqttClient

概要#

属性#

  • autoKeepAliveᅟ - This property holds whether the client will automatically manage keep alive messages to the server

  • cleanSessionᅟ - This property holds the state after connecting to a broker

  • clientIdᅟ - This property holds the client’s identifier value

  • errorᅟ - Specifies the current error of the client

  • hostname键 - 该属性持有关联到MQTT代理的主机名

  • keepAlive键 - 该属性持有关于定期向代理发送ping消息的间隔

  • password键 - 该属性持有关联到代理的密码

  • port键 - 该属性持有关联到MQTT代理的端口号

  • protocolVersion键 - 该属性持有关于连接要使用的MQTT标准版本

  • state键 - 该属性持有关于客户端的当前状态

  • username键 - 该属性持有关联到代理的用户名

  • willMessage键 - 该属性持有关于Will消息的有效负载

  • willQoS键 - 该属性持有关于发送和存储Will消息的QoS级别

  • willRetain键 - 该属性持有关于Will消息是否应在代理上保留以供未来的订阅者接收

  • willTopic键 - 该属性持有关于Will主题

方法#

槽（Slots）#

信号##

注意

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

详细描述#

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

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

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协议第五级相关。原因代码可能提供更多详细信息。
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。

访问函数
属性cleanSession: bool#

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

访问函数
属性clientId: str#

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

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

访问函数
属性error: QMqttClient.ClientError#

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

访问函数
属性hostname: str#

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

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

访问函数
属性keepAlive: int#

该属性保存发送ping消息到代理的间隔。

当与代理之间的连接建立后，客户端需要频繁发送更新以保持其可达性。这些更新的间隔由该属性指定。

间隔以秒为单位。

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

访问函数
属性 password⋅: str#

该属性包含连接到代理的密码。

访问函数
属性 port⋅: int#

该属性包含连接到MQTT代理的端口。

如果没有通过setTransport()指定传输，客户端将使用此端口号创建一个主机的套接字连接。

访问函数
属性 protocolVersion⋅: QMqttClient.ProtocolVersion#

该属性包含连接所使用的MQTT标准的版本。

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

  • 3: MQTT标准版本3.1。

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

访问函数
属性 state⋅: QMqttClient.ClientState#

该属性包含客户端当前的连接状态。

访问函数
属性 username: str#

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

访问函数
属性 willMessage: QByteArray#

该属性用于保存 Will 消息的负载。

访问函数
属性 willQoS: int#

该属性用于保存发送和存储 Will 消息的 QoS 级别。

访问函数
属性 willRetain: bool#

该属性用于保存 Will 消息是否应该在代理中保留，以便后续订阅者接收。

访问函数
属性 willTopic: str#

该属性用于保存 Will 主题。

访问函数
__init__([parent=None])#
参数::

parent - QObject

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

authenticate(prop)#
参数::

prop – QMqttAuthenticationProperties

向代理发送身份验证请求。prop指定满足身份验证请求所需的信息。

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

注意

扩展身份验证是MQTT 5.0标准的一部分，并且只能在客户端将MQTT_5_0指定为ProtocolVersion时使用。

另请参阅

authenticationRequested authenticationFinished

authenticationFinished(p)#
参数::

p – QMqttAuthenticationProperties

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

在成功验证后，发出connected。

注意

扩展身份验证是MQTT 5.0标准的一部分，并且只能在客户端将MQTT_5_0指定为ProtocolVersion时使用。

另请参阅

authenticationRequested() authenticate()

authenticationRequested(p)#
参数::

p – QMqttAuthenticationProperties

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

注意

扩展身份验证是MQTT 5.0标准的一部分，并且只能在客户端将MQTT_5_0指定为ProtocolVersion时使用。

另请参阅

authenticationFinished() authenticate()

autoKeepAlive()#
返回类型:

bool

另请参阅

setAutoKeepAlive()

属性 autoKeepAlive 的获取器。

autoKeepAliveChanged(autoKeepAlive)#
参数::

autoKeepAlive - bool

属性 autoKeepAlive 的通知信号。

brokerSessionRestored()#

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

如果客户端先前已使用相同的 clientId 连接，则可以恢复会话。

cleanSession()#
返回类型:

bool

另请参阅

setCleanSession()

属性 cleanSession 的获取器。

cleanSessionChanged(cleanSession)#
参数::

cleanSession - bool

属性 cleanSession 的通知信号。

clientId()#
返回类型:

str

另请参阅

setClientId()

属性 clientId 的获取器。

clientIdChanged(clientId)#
参数::

clientId - str

属性 clientId 的通知信号。

connectToHost()#

启动与 MQTT 代理的连接。

connectToHostEncrypted(conf)#
参数::

conf – QSslConfiguration

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

conf指定连接所使用的SSL配置

connected()#

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

connectionProperties()#
返回类型:

QMqttConnectionProperties

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

注意

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

另请参阅

setConnectionProperties()

disconnectFromHost()#

断开与MQTT代理的连接。

disconnected()#

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

error()#
返回类型:

ClientError

另请参阅

setError()

属性error的获取器。

errorChanged(error)#
参数::

error – ClientError

属性error的通知信号。

hostname()#
返回类型:

str

另请参阅

setHostname()

属性hostname的获取器。

hostnameChanged(hostname)#
参数::

hostname – 字符串

属性 hostname 的通知信号。

keepAlive()#
返回类型:

int

另请参阅

setKeepAlive()

获取属性 keepAlive 的值。

keepAliveChanged(keepAlive)#
参数::

keepAlive – int

属性 keepAlive 的通知信号。

lastWillProperties()#
返回类型:

QMqttLastWillProperties

返回最后的意愿属性。

注意

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

另请参阅

setLastWillProperties()

messageReceived(message[, topic=QMqttTopicName()])#
参数::

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

messageSent(id)#
参数::

id – int

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

messageStatusChanged(id, s, properties)#
参数::

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

password()#
返回类型:

str

另请参阅

setPassword()

属性 password 的获取器。

passwordChanged(password)#
参数::

password – str

属性 password 的通知信号。

pingResponseReceived()#

在经纪人对 requestPing() 调用或 keepAlive() ping 消息进行响应，并且连接仍然有效之后，会发出此信号。

port()#
返回类型:

int

另请参阅

setPort()

属性 port 的获取器。

portChanged(port)#
参数::

port – int

属性 port 的通知信号。

protocolVersion()#
返回类型:

ProtocolVersion

另请参阅

setProtocolVersion()

属性 protocolVersion 的获取器。

protocolVersionChanged(protocolVersion)#
参数::

protocolVersion – ProtocolVersion

属性 protocolVersion 的通知信号。

publish(topic[, message=QByteArray()[, qos=0[, retain=false]]])#
参数::
返回类型:

int

向指定主题的代理发送一个消息。 qos指定了传输消息所需的QoS（服务质量）级别。

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

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

publish(topic, properties[, message=QByteArray()[, qos=0[, retain=false]]])
参数::
返回类型:

int

使用指定的属性和主题将消息发布到代理。 qos指定了传输消息所需的QoS（服务质量）级别。

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

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

注意

属性将仅在客户端将ProtocolVersion设置为MQTT_5_0时传递给代理。

requestPing()#
返回类型:

bool

向代理发送ping消息并期望收到回复。

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

使用requestPing()需要手动调用，而且每次必须在keepAlive间隔之内，只要连接处于活动状态。

要检查ping是否成功，请连接到pingResponseReceived()（ping响应接收）信号。

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

serverConnectionProperties()#
返回类型:

QMqttServerConnectionProperties

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

这可以用来验证通过 setConnectionProperties 设置的客户端连接属性已被代理接受。另外，在连接尝试失败的情况下，可以用作连接诊断。

注意

QMqttServerConnectionProperties 仅当客户端指定 MQTT_5_0 作为 ProtocolVersion 时可以使用。

另请参阅

connectionProperties()

setAutoKeepAlive(autoKeepAlive)#
参数::

autoKeepAlive - bool

另请参阅

autoKeepAlive()

autoKeepAlive 属性的设置器。

setCleanSession(cleanSession)#
参数::

cleanSession - bool

另请参阅

cleanSession()

cleanSession 属性的设置器。

setClientId(clientId)#
参数::

clientId - str

另请参阅

clientId()

clientId 属性的设置器。

setConnectionProperties(prop)#
参数::

prop – QMqttConnectionProperties

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

注意

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

注意

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

另请参阅

connectionProperties()

setError(error)#
参数::

error – ClientError

另请参阅

error()

属性 error属性 的设置器。

setHostname(hostname)#
参数::

hostname – 字符串

另请参阅

hostname()

属性 hostname属性 的设置器。

setKeepAlive(keepAlive)#
参数::

keepAlive – int

另请参阅

keepAlive()

属性 keepAlive属性 的设置器。

setLastWillProperties(prop)#
参数::

prop – QMqttLastWillProperties

将最后的意志属性设置为 prop。 QMqttLastWillProperties 允许为存储在代理服务器上的最后意志消息设置附加功能。

注意

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

注意

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

另请参阅

lastWillProperties()

setPassword(password)#
参数::

password – str

另请参阅

password()

属性 password属性 的设置器。

setPort(port)#
参数::

port – int

另请参阅

port()

属性 port属性 的设置器。

setProtocolVersion(protocolVersion)#
参数::

protocolVersion – ProtocolVersion

另请参阅

protocolVersion()

属性 protocolVersion属性 的设置器。

setState(state)#
参数::

state – ClientState

另请参阅

state()

属性 state属性 的设置器。

setTransport(device, transport)#
参数::

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

注意

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

注意

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

另请参阅

transport()

setUsername(username)#
参数::

用户名 – str

另请参阅

username()

username 属性的设置器。

setWillMessage(willMessage)#
参数::

遗嘱消息 – QByteArray

另请参阅

willMessage()

willMessage 属性的设置器。

setWillQoS(willQoS)#
参数::

遗嘱服务质量 – int

另请参阅

willQoS()

willQoS 属性的设置器。

setWillRetain(willRetain)#
参数::

遗嘱保留 – bool

另请参阅

willRetain()

willRetain 属性的设置器。

setWillTopic(willTopic)#
参数::

遗嘱主题 – str

另请参阅

willTopic()

willTopic 属性的设置器。

state()#
返回类型:

ClientState

另请参阅

setState()

state 属性的获取器。

stateChanged(状态)#
参数::

state – ClientState

属性 stateᅟ 的通知信号。

subscribe(topic, properties[, qos=0])#
参数::
返回类型:

QMqttSubscription

添加新的订阅，以接收有关 topic 的通知。参数 properties 指定了需要由代理验证的附加订阅属性。参数 qos 指定了接收安全消息的级别。有关可用的 QoS 级别更多信息，请参阅 服务质量。

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

注意

属性将仅在客户端将ProtocolVersion设置为MQTT_5_0时传递给代理。

subscribe(topic[, qos=0])
参数::
返回类型:

QMqttSubscription

添加新的订阅以接收有关 topic 的通知。参数 qos 指定了接收安全消息的级别。有关可用的 QoS 级别更多信息，请参阅 服务质量。

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

transport()#
返回类型:

QIODevice

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

另请参阅

setTransport()

unsubscribe(topic)#
参数::

topic – QMqttTopicFilter

从 topic 取消订阅。调用 subscribe() 所进行的任何订阅都不会收到通知。

注意

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

unsubscribe(topic, properties)
参数::

从 topic 中取消订阅。将不会向通过调用 subscribe() 制作的任何订阅发送通知。properties 指定了要传递给代理的附加用户属性。

注意

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

注意

属性将仅在客户端将ProtocolVersion设置为MQTT_5_0时传递给代理。

username()#
返回类型:

str

另请参阅

setUsername()

属性 username 的获取器。

usernameChanged(username)#
参数::

用户名 – str

属性 username 的通知信号。

willMessage()#
返回类型:

QByteArray

另请参阅

setWillMessage()

属性 willMessage 的获取器。

willMessageChanged(willMessage)#
参数::

遗嘱消息 – QByteArray

属性 willMessage 的通知信号。

willQoS()#
返回类型:

int

另请参阅

setWillQoS()

属性 willQoS 的获取器。

willQoSChanged(willQoS)#
参数::

遗嘱服务质量 – int

属性 willQoS 的通知信号。

willRetain()#
返回类型:

bool

另请参阅

setWillRetain()

属性 willRetain 的获取器。

willRetainChanged(willRetain)#
参数::

遗嘱保留 – bool

属性 willRetain 的通知信号。

willTopic()#
返回类型:

str

另请参阅

setWillTopic()

属性 willTopic 的获取器。

willTopicChanged(willTopic)#
参数::

遗嘱主题 – str

属性通知信号 willTopicᅟ。