feat: Add API to get MQTT client's status

Add a function which returns the status of MQTT client, either initialized,
connected, reconnecting, or disconnected.

Closes https://github.com/espressif/esp-mqtt/issues/307

docs/sphinx-known-warnings.txt

@@ -12,6 +12,8 @@ mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:
 Declaration is '.. cpp:enum:: esp_mqtt_transport_t'.
 mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
 Declaration is '.. cpp:enum:: esp_mqtt_protocol_ver_t'.
+mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
+Declaration is '.. cpp:enum:: esp_mqtt_client_connection_state_t'.
 mqtt5_client.inc:line: WARNING: Duplicate C++ declaration, also defined at index:line.
 Declaration is '.. cpp:enumerator:: __attribute__'.
 index.rst:line: CRITICAL: Duplicate ID: "mqtt5__client_8h_1a4504a6557b6b27d66613101e758693f4a8c1dfc1ccf00a08192611433ee7f17b4".

include/mqtt_client.h

@@ -153,6 +153,17 @@ typedef enum esp_mqtt_protocol_ver_t {
     MQTT_PROTOCOL_V_5,
 } esp_mqtt_protocol_ver_t;
 
+/**
+ * States of MQTT client connection
+ */
+typedef enum esp_mqtt_client_connection_state_t {
+    MQTT_CLIENT_STATE_NOT_INITIALIZED = 0,  /*!< MQTT Client is not initialized */
+    MQTT_CLIENT_STATE_NOT_STARTED,          /*!< MQTT Client is initialized, but not started */
+    MQTT_CLIENT_STATE_DISCONNECTED,         /*!< MQTT Client is started, but not connected to the broker */
+    MQTT_CLIENT_STATE_CONNECTED,            /*!< MQTT Client is connected to the broker */
+    MQTT_CLIENT_STATE_WAITING_RECONNECT,    /*!< MQTT Client is waiting for reconnection request */
+} esp_mqtt_client_connection_state_t;
+
 /**
  * @brief *MQTT* error code structure to be passed as a contextual information
  * into ERROR event
@@ -706,6 +717,19 @@ esp_err_t esp_mqtt_dispatch_custom_event(esp_mqtt_client_handle_t client, esp_mq
  *
 */
 esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t client, char *transport_scheme);
+
+/**
+ * @brief Get MQTT client's current state
+ *
+ * Get the current state of MQTT client. Returns a value to indicate whether is it initialized, connected, waiting for
+ * reconnection, or disconnected.
+ *
+ * @param client            *MQTT* client handle
+ * @return MQTT client state on success
+ *         MQTT_CLIENT_STATE_INVALID in case of error
+ */
+esp_mqtt_client_connection_state_t esp_mqtt_client_get_state(esp_mqtt_client_handle_t client);
+
 #ifdef __cplusplus
 }
 #endif //__cplusplus

mqtt_client.c

@@ -1033,6 +1033,7 @@ _mqtt_init_failed:
 esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client)
 {
     if (client == NULL) {
+        ESP_LOGD(TAG, "Unable to destroy client - client handle is NULL");
         return ESP_ERR_INVALID_ARG;
     }
 
@@ -2636,6 +2637,7 @@ esp_err_t esp_mqtt_client_register_event(esp_mqtt_client_handle_t client, esp_mq
                                          esp_event_handler_t event_handler, void *event_handler_arg)
 {
     if (client == NULL) {
+        ESP_LOGD(TAG, "Unable to register event - client handle is NULL");
         return ESP_ERR_INVALID_ARG;
     }
 
@@ -2652,6 +2654,7 @@ esp_err_t esp_mqtt_client_unregister_event(esp_mqtt_client_handle_t client, esp_
                                            esp_event_handler_t event_handler)
 {
     if (client == NULL) {
+        ESP_LOGD(TAG, "Unable to unregister event - client handle is NULL");
         return ESP_ERR_INVALID_ARG;
     }
 
@@ -2688,6 +2691,7 @@ int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client)
     int outbox_size = 0;
 
     if (client == NULL) {
+        ESP_LOGE(TAG, "Unable to get outbox size - client handle is NULL");
         return 0;
     }
 
@@ -2703,7 +2707,13 @@ int esp_mqtt_client_get_outbox_size(esp_mqtt_client_handle_t client)
 
 esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t client, char *transport_scheme)
 {
-    if (client == NULL || (transport_scheme == NULL && client->config->transport == NULL)) {
+    if (client == NULL) {
+        ESP_LOGE(TAG, "Unable to get transport - client handle is NULL");
+        return NULL;
+    }
+
+    if (transport_scheme == NULL && client->config->transport == NULL) {
+        ESP_LOGE(TAG, "Unable to get transport - no transport scheme set and no transport provided");
         return NULL;
     }
 
@@ -2713,3 +2723,39 @@ esp_transport_handle_t esp_mqtt_client_get_transport(esp_mqtt_client_handle_t cl
 
     return esp_transport_list_get_transport(client->transport_list, transport_scheme);
 }
+
+esp_mqtt_client_connection_state_t esp_mqtt_client_get_state(esp_mqtt_client_handle_t client)
+{
+    if (client == NULL) {
+        ESP_LOGD(TAG, "Unable to get MQTT client state - client handle is NULL");
+        return MQTT_CLIENT_STATE_NOT_INITIALIZED;
+    }
+
+    if (client->task_handle == NULL) {
+        return MQTT_CLIENT_STATE_NOT_STARTED;
+    }
+
+    MQTT_API_LOCK(client);
+    esp_mqtt_client_connection_state_t ret = MQTT_CLIENT_STATE_NOT_INITIALIZED;
+
+    switch (client->state) {
+    case MQTT_STATE_INIT:
+        ret = MQTT_CLIENT_STATE_NOT_STARTED;
+        break;
+
+    case MQTT_STATE_CONNECTED:
+        ret = MQTT_CLIENT_STATE_CONNECTED;
+        break;
+
+    case MQTT_STATE_WAIT_RECONNECT:
+        ret = MQTT_CLIENT_STATE_WAITING_RECONNECT;
+        break;
+
+    case MQTT_STATE_DISCONNECTED:
+        ret = MQTT_CLIENT_STATE_DISCONNECTED;
+        break;
+    }
+
+    MQTT_API_UNLOCK(client);
+    return ret;
+}