QMqttClient Class▲
-
Header: QMqttClient
-
qmake: QT += mqtt
-
Inherits: QObject
Detailed Description▲
An MQTT client is a program or device that uses MQTT to create a network connection to an MQTT server, also called a broker. The connection request must contain a unique client identifier. Optionally, it can contain a Will Topic, Will Message, user name, and password.
Once a connection is created, a client can send messages that other clients might be interested in receiving, subscribe to request notifications on topics, unsubscribe to remove a request for notifications, and disconnect from the broker.
Member Type Documentation▲
enum QMqttClient::ClientError▲
This enum type specifies the error state of a client.
|
Constant |
Value |
Description |
|---|---|---|
|
QMqttClient::NoError |
0 |
No error occurred. |
|
QMqttClient::InvalidProtocolVersion |
1 |
The broker does not accept a connection using the specified protocol version. |
|
QMqttClient::IdRejected |
2 |
The client ID is malformed. This might be related to its length. |
|
QMqttClient::ServerUnavailable |
3 |
The network connection has been established, but the service is unavailable on the broker side. |
|
QMqttClient::BadUsernameOrPassword |
4 |
The data in the username or password is malformed. |
|
QMqttClient::NotAuthorized |
5 |
The client is not authorized to connect. |
|
QMqttClient::TransportInvalid |
256 |
The underlying transport caused an error. For example, the connection might have been interrupted unexpectedly. |
|
QMqttClient::ProtocolViolation |
257 |
The client encountered a protocol violation, and therefore closed the connection. |
|
QMqttClient::UnknownError |
258 |
An unknown error occurred. |
|
QMqttClient::Mqtt5SpecificError |
259 |
The error is related to MQTT protocol level 5. A reason code might provide more details. |
enum QMqttClient::ClientState▲
This enum type specifies the states a client can enter.
|
Constant |
Value |
Description |
|---|---|---|
|
QMqttClient::Disconnected |
0 |
The client is disconnected from the broker. |
|
QMqttClient::Connecting |
1 |
A connection request has been made, but the broker has not approved the connection yet. |
|
QMqttClient::Connected |
2 |
The client is connected to the broker. |
enum QMqttClient::ProtocolVersion▲
This enum specifies the protocol version of the MQTT standard to use during communication with a broker.
|
Constant |
Value |
Description |
|---|---|---|
|
QMqttClient::MQTT_3_1 |
3 |
MQTT Standard 3.1 |
|
QMqttClient::MQTT_3_1_1 |
4 |
MQTT Standard 3.1.1, publicly referred to as version 4 |
|
QMqttClient::MQTT_5_0 |
5 |
MQTT Standard 5.0 |
enum QMqttClient::TransportType▲
This enum type specifies the connection method to be used to instantiate a connection to a broker.
|
Constant |
Value |
Description |
|---|---|---|
|
QMqttClient::IODevice |
0 |
The transport uses a class based on a QIODevice. |
|
QMqttClient::AbstractSocket |
1 |
The transport uses a class based on a QAbstractSocket. |
|
QMqttClient::SecureSocket |
2 |
The transport uses a class based on a QSslSocket. |
Property Documentation▲
[since 5.14] autoKeepAlive : bool▲
This property holds whether the client will automatically manage keep alive messages to the server.
If this property is true, then the client will automatically send a ping message to the server at the keepAlive interval.
Otherwise, a user will have to manually invoke requestPing within the specified interval of the connection. If no ping has been sent within the interval, the server will disconnect.
The default of this property is true.
This property was introduced in Qt 5.14.
Access functions:
-
bool autoKeepAlive() const
-
void setAutoKeepAlive(bool autoKeepAlive)
Notifier signal:
-
void autoKeepAliveChanged(bool autoKeepAlive)
See Also▲
See also keepAlive(), requestPing(), serverConnectionProperties(), pingResponseReceived()
cleanSession : bool▲
This property holds the state after connecting to a broker.
Access functions:
-
bool cleanSession() const
-
void setCleanSession(bool cleanSession)
Notifier signal:
-
void cleanSessionChanged(bool cleanSession)
clientId : QString▲
This property holds the client's identifier value.
Each client needs to have a unique ID to be able to connect to an MQTT broker. If no client ID is specified by the user, one will be generated automatically when a connection is established.
Access functions:
-
clientId() const
-
void setClientId(const &clientId)
Notifier signal:
-
void clientIdChanged( clientId)
error : ClientError▲
Specifies the current error of the client.
Access functions:
-
error() const
-
void setError( error)
Notifier signal:
-
void errorChanged( error)
hostname : QString▲
This property holds the hostname of the MQTT broker to connect to.
If no transport is specified via setTransport(), the client will instantiate a socket connection to the specified hostname itself.
Access functions:
-
hostname() const
-
void setHostname(const &hostname)
Notifier signal:
-
void hostnameChanged( hostname)
keepAlive : quint16▲
This property holds the interval at which regular ping messages are sent to the broker.
Once a connection to a broker is established, the client needs to send frequent updates to propagate it can still be reached. The interval between those updates is specified by this property.
The interval is specified in seconds.
If the broker does not respond within a grace period the connection will be closed.
Access functions:
-
keepAlive() const
-
void setKeepAlive( keepAlive)
Notifier signal:
-
void keepAliveChanged( keepAlive)
See Also▲
See also autoKeepAlive(), requestPing(), pingResponseReceived()
password : QString▲
This property holds the password for connecting to a broker.
Access functions:
-
password() const
-
void setPassword(const &password)
Notifier signal:
-
void passwordChanged( password)
port : quint16▲
This property holds the port to connect to the MQTT broker.
If no transport is specified via setTransport(), the client will instantiate a socket connection to a host with this port number.
Access functions:
-
port() const
-
void setPort( port)
Notifier signal:
-
void portChanged( port)
protocolVersion : ProtocolVersion▲
This property holds the MQTT standard version to use for connections.
Specifies the version of the standard the client uses for connecting to a broker. Valid values are:
-
3: MQTT standard version 3.1.
-
4: MQTT standard version 3.1.1, often referred to MQTT 4.
Access functions:
-
protocolVersion() const
-
void setProtocolVersion( protocolVersion)
Notifier signal:
-
void protocolVersionChanged( protocolVersion)
state : ClientState▲
This property holds the current state of the client.
Access functions:
-
state() const
-
void setState( state)
Notifier signal:
-
void stateChanged( state)
username : QString▲
This property holds the user name for connecting to a broker.
Access functions:
-
username() const
-
void setUsername(const &username)
Notifier signal:
-
void usernameChanged( username)
willMessage : QByteArray▲
This property holds the payload of a Will Message.
Access functions:
-
willMessage() const
-
void setWillMessage(const &willMessage)
Notifier signal:
-
void willMessageChanged( willMessage)
willQoS : quint8▲
This property holds the level of QoS for sending and storing the Will Message.
Access functions:
-
willQoS() const
-
void setWillQoS( willQoS)
Notifier signal:
-
void willQoSChanged( willQoS)
willRetain : bool▲
This property holds whether the Will Message should be retained on the broker for future subscribers to receive.
Access functions:
-
bool willRetain() const
-
void setWillRetain(bool willRetain)
Notifier signal:
-
void willRetainChanged(bool willRetain)
willTopic : QString▲
This property holds the Will Topic.
Access functions:
-
willTopic() const
-
void setWillTopic(const &willTopic)
Notifier signal:
-
void willTopicChanged( willTopic)
Member Function Documentation▲
[override virtual] QMqttClient::~QMqttClient()▲
Deletes a MQTT client. If the MQTT client was not already disconnected from the MQTT broker, it will be disconnected from automatically.
[since 5.12] void QMqttClient::authenticate(const int &prop)▲
Sends an authentication request to the broker. prop specifies the required information to fulfill the authentication request.
This function should only be called after a QMqttClient::authenticationRequested signal has been emitted.
Extended authentication is part of the MQTT 5.0 standard and can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
See Also▲
See also authenticationRequested(), authenticationFinished()
[since 5.12] void QMqttClient::authenticationFinished(const int &p)▲
This signal is emitted after extended authentication has finished. p specifies available details on the authentication process.
After successful authentication QMqttClient::connected is emitted.
Extended authentication is part of the MQTT 5.0 standard and can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
See Also▲
See also authenticationRequested(), authenticate()
[since 5.12] void QMqttClient::authenticationRequested(const int &p)▲
This signal is emitted after a client invoked QMqttClient::connectToHost or QMqttClient::connectToHostEncrypted and before the connection is established. In extended authentication, a broker might request additional details which need to be provided by invoking QMqttClient::authenticate. p specifies properties provided by the broker.
Extended authentication is part of the MQTT 5.0 standard and can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
See Also▲
See also authenticationFinished(), authenticate()
void QMqttClient::brokerSessionRestored()▲
This signal is emitted after a client has successfully connected to a broker with the cleanSession property set to false, and the broker has restored the session.
Sessions can be restored if a client has connected previously using the same clientId.
void QMqttClient::connectToHost()▲
Initiates a connection to the MQTT broker.
[since 5.14] void QMqttClient::connectToHostEncrypted(const QSslConfiguration &conf)▲
Initiates an encrypted connection to the MQTT broker.
conf specifies the SSL configuration to be used for the connection
This function was introduced in Qt 5.14.
void QMqttClient::connected()▲
This signal is emitted when a connection has been established.
[since 5.12] int QMqttClient::connectionProperties() const▲
Returns the connection properties the client requests to the broker.
QMqttConnectionProperties can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
void QMqttClient::disconnectFromHost()▲
Disconnects from the MQTT broker.
void QMqttClient::disconnected()▲
This signal is emitted when a connection has been closed. A connection may be closed when disconnectFromHost() is called or when the broker disconnects.
[since 5.12] int QMqttClient::lastWillProperties() const▲
Returns the last will properties.
QMqttLastWillProperties can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
void QMqttClient::messageReceived(const QByteArray &message, const QMqttTopicName &topic = QMqttTopicName())▲
This signal is emitted when a new message has been received. The category of the message is specified by topic with the content being message.
void QMqttClient::messageSent(qint32 id)▲
Indicates that a message that was sent via the publish() function has been received by the broker. The id is the same as returned by publish() to help tracking the status of the message.
void QMqttClient::pingResponseReceived()▲
This signal is emitted after the broker responds to a requestPing() call or a keepAlive() ping message, and the connection is still valid.
qint32 QMqttClient::publish(const QMqttTopicName &topic, const QByteArray &message = QByteArray(), quint8 qos = 0, bool retain = false)▲
Publishes a message to the broker with the specified topic. qos specifies the QoS level required for transferring the message.
If retain is set to true, the message will stay on the broker for other clients to connect and receive the message.
Returns an ID that is used internally to identify the message.
bool QMqttClient::requestPing()▲
Sends a ping message to the broker and expects a reply.
If the connection is active and autoKeepAlive is true, then calling this function will fail as the client is responsible for managing this process.
Using requestPing() manually requires a call every time within the keepAlive interval as long as the connection is active.
To check whether the ping is successful, connect to the pingResponseReceived() signal.
Returns true if the ping request could be sent.
See Also▲
See also pingResponseReceived(), autoKeepAlive(), keepAlive()
[since 5.12] int QMqttClient::serverConnectionProperties() const▲
Returns the QMqttServerConnectionProperties the broker returned after a connection attempt.
This can be used to verify that client side connection properties set by QMqttClient::setConnectionProperties have been accepted by the broker. Also, in case of a failed connection attempt, it can be used for connection diagnostics.
QMqttServerConnectionProperties can only be used when the client specifies MQTT_5_0 as ProtocolVersion.
This function was introduced in Qt 5.12.
See Also▲
See also connectionProperties()
void QMqttClient::setTransport(QIODevice *device, QMqttClient::TransportType transport)▲
Sets the transport to device. A transport can be either a socket type or derived from QIODevice and is specified by transport.
The transport can only be exchanged if the MQTT client is in the Disconnected state.
Setting a custom transport for a client does not pass over responsibility on connection management. The transport has to be opened for QIODevice based transports or connected for socket type transports before calling QMqttClient::connectToHost().
See Also▲
See also transport()