QT/Serial-Studio
1
0
Fork 0
mirror of https://github.com/Serial-Studio/Serial-Studio.git synced 2025-01-31 17:42:55 +08:00
Code Issues Projects Releases Wiki Activity
Serial-Studio/lib/qmqtt/qmqtt-API.md
Alex Spataru 87a8329c84 Move project to CMake
2024-08-10 12:58:21 -05:00

596 lines
17 KiB
Markdown
Raw Permalink Blame History

# qmqtt API
```C++
enum ClientError
{
UnknownError = 0,
SocketConnectionRefusedError,
SocketRemoteHostClosedError,
SocketHostNotFoundError,
SocketAccessError,
SocketResourceError,
SocketTimeoutError,
SocketDatagramTooLargeError,
SocketNetworkError,
SocketAddressInUseError,
SocketAddressNotAvailableError,
SocketUnsupportedSocketOperationError,
SocketUnfinishedSocketOperationError,
SocketProxyAuthenticationRequiredError,
SocketSslHandshakeFailedError,
SocketProxyConnectionRefusedError,
SocketProxyConnectionClosedError,
SocketProxyConnectionTimeoutError,
SocketProxyNotFoundError,
SocketProxyProtocolError,
SocketOperationError,
SocketSslInternalError,
SocketSslInvalidUserDataError,
SocketTemporaryError,
MqttUnacceptableProtocolVersionError=1<<16,
MqttIdentifierRejectedError,
MqttServerUnavailableError,
MqttBadUserNameOrPasswordError,
MqttNotAuthorizedError,
MqttNoPingResponse
}
```
This enum describes the client errors that can occur.
| Constant | Value | Description |
| :--------------------------------------- | ------- | ------------------------------------------------------------ |
| `UnknownError ` | `0` | An unidentified error occurred. |
| `SocketConnectionRefusedError` | `1` | The connection was refused by the peer (or timed out). |
| `SocketRemoteHostClosedError` | `2` | The remote host closed the connection. Note that the client socket (i.e., this socket) will be closed after the remote close notification has been sent. |
| `SocketHostNotFoundError` | `3` | The host address was not found. |
| `SocketAccessError` | `4` | The socket operation failed because the application lacked the required privileges. |
| `SocketResourceError` | `5` | The local system ran out of resources (e.g., too many sockets). |
| `SocketTimeoutError` | `6` | The socket operation timed out. |
| `SocketDatagramTooLargeError` | `7` | The datagram was larger than the operating system's limit (which can be as low as 8192 bytes). |
| `SocketNetworkError` | `8` | An error occurred with the network (e.g., the network cable was accidentally plugged out). |
| `SocketAddressInUseError` | `9` | The address is already in use and was set to be exclusive. |
| `SocketAddressNotAvailableError` | `10` | The address does not belong to the host. |
| `SocketUnsupportedSocketOperationError` | `11` | The requested socket operation is not supported by the local operating system (e.g., lack of IPv6 support). |
| `SocketUnfinishedSocketOperationError` | `12` | Used by QAbstractSocketEngine only, The last operation attempted has not finished yet (still in progress in the background). |
| `SocketProxyAuthenticationRequiredError` | `13` | The socket is using a proxy, and the proxy requires authentication. |
| `SocketSslHandshakeFailedError` | `14` | The SSL/TLS handshake failed, so the connection was closed. |
| `SocketProxyConnectionRefusedError` | `15` | Could not contact the proxy server because the connection to that server was denied |
| `SocketProxyConnectionClosedError` | `16` | The connection to the proxy server was closed unexpectedly (before the connection to the final peer was established) |
| `SocketProxyConnectionTimeoutError` | `17` | The connection to the proxy server timed out or the proxy server stopped responding in the authentication phase. |
| `SocketProxyNotFoundError` | `18` | The proxy address set with (or the application proxy) was not found. |
| `SocketProxyProtocolError` | `19` | The connection negotiation with the proxy server failed, because the response from the proxy server could not be understood. |
| `SocketOperationError` | `20` | An operation was attempted while the socket was in a state that did not permit it. |
| `SocketSslInternalError` | `21` | The SSL library being used reported an internal error. This is probably the result of a bad installation or misconfiguration of the library. |
| `SocketSslInvalidUserDataError` | `22` | Invalid data (certificate, key, cypher, etc.) was provided and its use resulted in an error in the SSL library. |
| `SocketTemporaryError` | `23` | A temporary error occurred (e.g., operation would block and socket is non-blocking). |
| `MqttUnacceptableProtocolVersionError` | `65536` | The **Server** does **not** support the **level** **of** the MQTT protocol requested **by** the **Client**. |
| `MqttIdentifierRejectedError` | `65537` | The **Client** identifier **is** correct UTF-8 but **not** allowed **by** the **Server**. |
| `MqttServerUnavailableError` | `65538` | The Network **Connection** has been made but the MQTT service **is** unavailable. |
| `MqttBadUserNameOrPasswordError` | `65539` | The **data** **in** the **user** **name** **or** **password** **is** malformed. |
| `MqttNotAuthorizedError` | `65540` | The **Client** **is** **not** authorized **to** **connect**. |
| `MqttNoPingResponse` | `65541` | Ping response timeout. |
#### Client Class
---
##### Public signals
| | Signals | Brief |
| ---- | :------------ | ----------------------------------- |
| void | `connected()` | Receive when connected. |
| void | `disconnected()` | Receive when disconnected. |
| void | `error(const QMQTT::ClientError error)` | Receive when client error occured. |
| void | `subscribed(const QString& topic, const quint8 qos)` | Receive when subscribe is succeeded. |
| void | `unsubscribed(const QString& topic)` | Receive when unsubscribe is succeeded. |
| void | `published(const quint16 msgid, const quint8 qos)` | Receive when publish is succeeded. |
| void | `pingresp()` | Receive when ping response is received. |
| void | `received(const QMQTT::Message& message)` | Receive when message is received. |
##### Public Functions
| Return | Function members | Brief |
| :-------- | :----------------------------------------------------------- | --------------------------------- |
| `Client` | `Client(const QHostAddress& host = QHostAddress::LocalHost, const quint16 port = 1883, QObject* parent = NULL);` | Constructor client object. |
| `void` | `setHost(const QHostAddress& host)` | Set host address. |
| `void` | `setHostName(const QString& hostName)` | Set host name. |
| `void` | `setPort(const quint16 port)` | Set port. |
| `void` | `setClientId(const QString& clientId)` | Set client identify. |
| `void` | `setUsername(const QString& username)` | Set user name. |
| `void` | `setPassword(const QByteArray& password)` | Set password. |
| `void` | `setVersion(const MQTTVersion version)` | Set mqtt version. |
| `void` | `setKeepAlive(const quint16 keepAlive)` | Set keep alive interval. |
| `void` | `setCleanSession(const bool cleanSession)` | Set clean session option. |
| `void` | `setAutoReconnect(const bool value)` | Set auto reconnect. |
| `void` | `setAutoReconnectInterval(const int autoReconnectInterval)` | Set auto reconnect interval. |
| `void` | `setWillTopic(const QString& willTopic)` | Set will topic. |
| `void` | `setWillQos(const quint8 willQos)` | Set will qos level. |
| `void` | `setWillRetain(const bool willRetain)` | Set will retain. |
| `void` | `setWillMessage(const QByteArray& willMessage)` | Set will message. |
| `void` | `connectToHost()` | Connect to host. |
| `void` | `disconnectFromHost()` | Disconnect from host. |
| `void` | `subscribe(const QString& topic, const quint8 qos = 0)` | Subscribe topic with certain qos. |
| `void` | `unsubscribe(const QString& topic)` | Unsubscribe a topic. |
| `quint16` | `publish(const QMQTT::Message& message)` | Publish a Message. |
Client
---
```c++
Client(const QHostAddress& host = QHostAddress::LocalHost,
const quint16 port = 1883,
QObject* parent = NULL);
```
Client constructor.
**Parameters**
- host: Host ip.
- port: Host port.
- parent: QObject.
**Returns**
- Client object.
setHost
---
`void setHost(const QHostAddress& host)`
Set host ip address. For example:
```C++
QMQTT::Client client;
const QHostAddress EXAMPLE_HOST = QHostAddress("34.211.84.46");
client.setHost(HOST);
```
**Parameters**
- host: Host ip.
**Returns**
setHostName
---
`setHostName(const QString& hostName)`
Set host name. For example:
```C++
QMQTT::Client client;
client.setHostName("broker.emqx.io");
```
**Parameters**
- hostName: Host name.
**Returns**
setPort
---
`setPort(const quint16 port)`
Set port num. For example:
```C++
QMQTT::Client client;
client.setPort(1883);
```
**Parameters**
- port: Port num.
**Returns**
setClientId
---
`setClientId(const QString& clientId)`
Set client identify. For example:
```C++
QMQTT::Client client;
client.setClientId("clientid");
```
**Parameters**
- clientId: Client identify.
**Returns**
setUsername
---
`void setUsername(const QString& username)`
Set username. For example:
```C++
QMQTT::Client client;
client.setUsername("username");
```
**Parameters**
- username: Username.
**Returns**
setVersion
---
`void setVersion(const MQTTVersion version)`
Set mqtt version. For example:
```C++
QMQTT::Client client;
client.setVersion(QMQTT::V3_1_1);
```
**Parameters**
- version: Mqtt version. For now only support 3.1.0 and 3.1.1.
**Returns**
setKeepAlive
---
`void setKeepAlive(const quint16 keepAlive);`
Set Keep alive interval. For example:
```C++
QMQTT::Client client;
client.setKeepAlive(100);
```
**Parameters**
- keepAlive: Keep alive interval, default is 300.
**Returns**
setCleanSession
---
`void setCleanSession(const bool cleanSession)`
Set clean session flag. For example:
```C++
QMQTT::Client client;
client.setCleanSession(true);
```
**Parameters**
- cleanSession: Set clean session, if true clean session, false keep session, default is false.
**Returns**
setAutoReconnect
---
`void setAutoReconnect(const bool value)`
Set auto reconnect. For example:
```C++
QMQTT::Client client;
client.setAutoReconnect(true);
```
**Parameters**
- value: Auto reconnect or not, true auto reconnect, false do not reconnect.
**Returns**
setAutoReconnectInterval
---
`void setAutoReconnectInterval(const int autoReconnectInterval)`
Set auto reconnect interval. For example:
```C++
QMQTT::Client client;
client.setAutoReconnectInterval(10);
```
**Parameters**
- autoReconnectInterval: Auto reconnect interval (second).
**Returns**
setWillTopic
---
`void setWillTopic(const QString& willTopic)`
Set will topic info. For example:
```C++
QMQTT::Client client;
client.setWillTopic("will topic");
```
**Parameters**
- willTopic: Will topic.
**Returns**
setWillQos
---
`void setWillQos(const quint8 willQos)`
Set will qos level. For example:
```C++
QMQTT::Client client;
client.setWillQos(1);
```
**Parameters**
- willQos: Will qos level.
**Returns**
setWillRetain
---
`void setWillRetain(const bool willRetain)`
Set will retain flag. For example:
```C++
QMQTT::Client client;
client.setWillRetain(true);
```
**Parameters**
- willRetain: Will retain flag.
**Returns**
setWillMessage
---
`void setWillMessage(const QByteArray& willMessage)`
Set will message. For example:
```C++
QMQTT::Client client;
QByteArray ba("Hello");
client.setWillMessage(ba);
```
**Parameters**
- willMessage: Will message.
**Returns**
connectToHost
---
`void connectToHost()`
Connect to host. For example:
```C++
QMQTT::Client client;
client.connectToHost();
```
**Parameters**
**Returns**
disconnectFromHost
---
`void disconnectFromHost()`
Disconnect from host. For example:
```C++
QMQTT::Client client;
client.disconnectFromHost();
```
**Parameters**
**Returns**
subscribe
---
`void subscribe(const QString& topic, const quint8 qos = 0)`
Subscribe a topic with a certain qos level.
```C++
QMQTT::Client client;
client.subscribe("topic", 1);
```
**Parameters**
- topic: subscribe topic.
- qos: subscribe topic qos level, default is 0.
**Returns**
unsubscribe
---
`void unsubscribe(const QString& topic)`
Unsubscribe a topic.
```C++
QMQTT::Client client;
client.unsubscribe("topic");
```
**Parameters**
- topic: unsubscribe topic.
**Returns**
publish
---
`quint16 publish(const QMQTT::Message& message)`
Publish a Message.
```C++
QMQTT::Client client;
QMQTT::Message message(1, "topic", QString("Hello").toUtf8());
message.setQos(2);
client.publish(message);
```
**Parameters**
- message: Message info see below.
**Returns**
#### Message Class
---
##### Public Functions
| Return | Function members | Brief |
| :----------- | :----------------------------------------------------------- | ------------------------- |
| `Message` | `Message()` | Construct Message object |
| `Message` | `Message(const quint16 id, const QString &topic, const QByteArray &payload, const quint8 qos = 0, const bool retain = false, const bool dup = false)` | Construct Message object |
| `Message` | `Message(const Message &other)` | Construct Message object |
| `Message` | `~Message()` | Destructor Message object |
| `quint16` | `id() const` | Get id |
| `void` | `setId(const quint16 id)` | Set id |
| `quint8` | `qos() const` | Get qos |
| `void` | `setQos(const quint8 qos)` | Set Qos |
| `bool` | `retain() const` | Get retain |
| `void` | `setRetain(const bool retain)` | Set retain |
| `bool` | `dup() const` | Get dup |
| `void` | `setDup(const bool dup)` | Set Dup |
| `QString` | `topic() const` | Get topic |
| `void` | `setTopic(const QString &topic)` | Set topic |
| `QByteArray` | `payload() const` | Get payload |
| `void` | `setPayload(const QByteArray &payload)` | Set payload |
Message
---
```C++
Message()
Message(const quint16 id, const QString &topic, const QByteArray &payload,const quint8 qos = 0, const bool retain = false, const bool dup = false)
Message(const Message &other)
```
id
---
`quint16 id() const`
Get id from Message.
**Parameters**
**Returns**
- Message identify.
setId
---
`void setId(const quint16 id)`
Set id to Message.
**Parameters**
- id: Message identify
**Returns**
qos
---
`quint8 qos() const`
Get qos level from Message.
**Parameters**
**Returns**
- Message qos level.
setQos
---
`void setQos(const quint8 qos)`
Set Message Qos level.
**Parameters**
- qos: Message qos level.
**Returns**
retain
---
`bool retain() const`
Get retain flag from Message.
**Parameters**
**Returns**
- Had retain flag been set.
setRetain
---
`void setRetain(const bool retain)`
Set retain flag to Message.
**Parameters**
- retain: Set retain flag.
**Returns**
dup
---
`bool dup() const`
Get dup flag from Message.
**Parameters**
**Returns**
- Dup flag been se.
setDup
---
`void setDup(const bool dup)`
Set dup flag for Message.
**Parameters**
- dup: Dup flag.
**Returns**
topic
---
`QString topic() const`
Get topic from Message.
**Parameters**
**Returns**
- Get Message topic.
setTopic
---
`void setTopic(const QString &topic)`
Set topic to Message.
**Parameters**
- topic: Set Message topic.
**Returns**
payload
---
`QByteArray payload() const`
Get payload form Message.
**Parameters**
**Returns**
- Message payload.
setPayload
---
`void setPayload(const QByteArray &payload)`
Set payload for Message.
**Parameters**
- payload: SetMessage payload.
**Returns**
Reference in New Issue View Git Blame Copy Permalink