From 4de0d2f9a4d34d87fa71f1614ff84988a39b32f6 Mon Sep 17 00:00:00 2001 From: Alex Spataru Date: Mon, 8 Mar 2021 03:48:15 -0500 Subject: [PATCH] Document MQTT module --- src/MQTT/Client.cpp | 105 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/src/MQTT/Client.cpp b/src/MQTT/Client.cpp index dad25248..7d3e75f5 100644 --- a/src/MQTT/Client.cpp +++ b/src/MQTT/Client.cpp @@ -30,8 +30,14 @@ using namespace MQTT; +/** + * The only instance of this class + */ static Client *INSTANCE = nullptr; +/** + * Constructor function + */ Client::Client() { m_lookupActive = false; @@ -45,7 +51,7 @@ Client::Client() connect(&m_client, &QMQTT::Client::connected, this, &Client::onConnectedChanged); connect(&m_client, &QMQTT::Client::disconnected, this, &Client::onConnectedChanged); - // Send data @ 1 Hz & reset statistics when disconnected/connected to a device + // Send data @ 42 Hz & reset statistics when disconnected/connected to a device auto io = IO::Manager::getInstance(); auto ge = JSON::Generator::getInstance(); auto te = Misc::TimerEvents::getInstance(); @@ -58,11 +64,17 @@ Client::Client() setHost(defaultHost()); } +/** + * Destructor function + */ Client::~Client() { disconnectFromHost(); } +/** + * Returns a pointer to the only instance of this class + */ Client *Client::getInstance() { if (!INSTANCE) @@ -71,16 +83,26 @@ Client *Client::getInstance() return INSTANCE; } +/** + * Returns the TCP port number used for the MQTT connection + */ quint16 Client::port() const { return m_client.port(); } +/** + * Returns the MQTT topic used + */ QString Client::topic() const { return m_topic; } +/** + * Returns the index of the MQTT version, corresponding to the list returned by the + * @c mqttVersions() function. + */ int Client::mqttVersion() const { switch (m_client.version()) @@ -97,51 +119,85 @@ int Client::mqttVersion() const } } +/** + * Returns the client mode, which can have the following values: + * - Publisher + * - Subscriber + */ int Client::clientMode() const { return m_clientMode; } +/** + * Returns the MQTT username + */ QString Client::username() const { return m_client.username(); } +/** + * Returns the MQTT password + */ QString Client::password() const { return QString::fromUtf8(m_client.password()); } +/** + * Returns the IP address of the MQTT broker/server + */ QString Client::host() const { return m_client.host().toString(); } +/** + * Returns @c true if the MQTT module is currently performing a DNS lookup of the MQTT + * broker/server domain. + */ bool Client::lookupActive() const { return m_lookupActive; } +/** + * Returns @c true if the MQTT module is connected to the broker, the topic is not empty + * and the client is configured to act as an MQTT subscriber. + */ bool Client::isSubscribed() const { return isConnectedToHost() && !topic().isEmpty() && clientMode() == ClientSubscriber; } +/** + * Returns @c true if the MQTT module is connected to a MQTT broker/server. + */ bool Client::isConnectedToHost() const { return m_client.isConnectedToHost(); } +/** + * Returns a list with the available client operation modes. + */ QStringList Client::clientModes() const { return QStringList { tr("Publisher"), tr("Subscriber") }; } +/** + * Returns a list with the supported MQTT versions + */ QStringList Client::mqttVersions() const { return QStringList { "MQTT 3.1.0", "MQTT 3.1.1" }; } +/** + * Tries to establish a TCP connection with the MQTT broker/server. + */ void Client::connectToHost() { m_client.connectToHost(); @@ -159,6 +215,9 @@ void Client::toggleConnection() connectToHost(); } +/** + * Disconnects from the MQTT broker/server + */ void Client::disconnectFromHost() { m_client.disconnectFromHost(); @@ -174,42 +233,65 @@ void Client::lookup(const QString &host) QHostInfo::lookupHost(host.simplified(), this, &Client::lookupFinished); } +/** + * Changes the TCP port number used for the MQTT communications. + */ void Client::setPort(const quint16 port) { m_client.setPort(port); emit portChanged(); } +/** + * Changes the IP address of the MQTT broker/host + */ void Client::setHost(const QString &host) { m_client.setHost(QHostAddress(host)); emit hostChanged(); } +/** + * Changes the operation mode of the MQTT client. Possible values are: + * - Publisher + * - Subscriber + */ void Client::setClientMode(const int mode) { m_clientMode = static_cast(mode); emit clientModeChanged(); } +/** + * Changes the MQTT topic used by the client. + */ void Client::setTopic(const QString &topic) { m_topic = topic; emit topicChanged(); } +/** + * Changes the username used to connect to the MQTT broker/server + */ void Client::setUsername(const QString &username) { m_client.setUsername(username); emit usernameChanged(); } +/** + * Changes the password used to connect to the MQTT broker/server + */ void Client::setPassword(const QString &password) { m_client.setPassword(password.toUtf8()); emit passwordChanged(); } +/** + * Changes the MQTT version used to connect to the MQTT broker/server + */ void Client::setMqttVersion(const int versionIndex) { switch (versionIndex) @@ -227,6 +309,10 @@ void Client::setMqttVersion(const int versionIndex) emit mqttVersionChanged(); } +/** + * Sorts all the received JSON frames and generates a partial CSV-file that is published + * to the MQTT broker/server + */ void Client::sendData() { // Sort JFI list from oldest to most recent @@ -274,12 +360,18 @@ void Client::sendData() m_jfiList.clear(); } +/** + * Clears the JSON frames & sets the sent messages to 0 + */ void Client::resetStatistics() { m_sentMessages = 0; m_jfiList.clear(); } +/** + * Subscribe/unsubscripe to the set MQTT topic when the connection state is changed. + */ void Client::onConnectedChanged() { if (isConnectedToHost()) @@ -310,6 +402,9 @@ void Client::lookupFinished(const QHostInfo &info) Misc::Utilities::showMessageBox(tr("IP address lookup error"), info.errorString()); } +/** + * Displays any MQTT-related error with a GUI message-box + */ void Client::onError(const QMQTT::ClientError error) { QString str; @@ -415,6 +510,10 @@ void Client::onError(const QMQTT::ClientError error) Misc::Utilities::showMessageBox(tr("MQTT client error"), str); } +/** + * Registers the given @a frameInfo structure to the JSON frames that shall be published + * to the MQTT broker/server + */ void Client::registerJsonFrame(const JFI_Object &frameInfo) { // Ignore if device is not connected @@ -430,6 +529,10 @@ void Client::registerJsonFrame(const JFI_Object &frameInfo) m_jfiList.append(frameInfo); } +/** + * Reads the given MQTT @a message and instructs the @c IO::Manager module to process + * received data directly. + */ void Client::onMessageReceived(const QMQTT::Message &message) { // Ignore if client mode is not set to suscriber