From 77a875c804c544fe8a9cf7856cfbb06d9c360dc6 Mon Sep 17 00:00:00 2001 From: Bogdan Kolendovskyy Date: Mon, 13 Oct 2025 16:13:54 +0200 Subject: [PATCH] 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 | 2 ++ include/mqtt_client.h | 24 +++++++++++++++++ mqtt_client.c | 48 +++++++++++++++++++++++++++++++++- 3 files changed, 73 insertions(+), 1 deletion(-) diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index cff318d..71339b2 100644 --- a/docs/sphinx-known-warnings.txt +++ b/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". diff --git a/include/mqtt_client.h b/include/mqtt_client.h index 5618f16..f292fd3 100644 --- a/include/mqtt_client.h +++ b/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 diff --git a/mqtt_client.c b/mqtt_client.c index fcca7da..4fe2859 100644 --- a/mqtt_client.c +++ b/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; +}