From e442c19f4e25cf778118e448e8fb0b7b747ee856 Mon Sep 17 00:00:00 2001 From: David Cermak Date: Mon, 6 May 2019 12:15:37 +0200 Subject: [PATCH] Added API documentaton to public headers --- include/mqtt_client.h | 123 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 2 deletions(-) diff --git a/include/mqtt_client.h b/include/mqtt_client.h index e4e11d4..dd1d7ef 100755 --- a/include/mqtt_client.h +++ b/include/mqtt_client.h @@ -44,6 +44,10 @@ typedef enum { - data_len length of the data for this event - current_data_offset offset of the current data for this event - total_data_len total length of the data received + Note: Multiple MQTT_EVENT_DATA could be fired for one message, if it is + longer than internal buffer. In that case only first event contains topic + pointer and length, other contain data only with current data length + and current data offset updating. */ MQTT_EVENT_BEFORE_CONNECT, /*!< The event occurs before connecting */ } esp_mqtt_event_id_t; @@ -107,15 +111,130 @@ typedef struct { int refresh_connection_after_ms; /*!< Refresh connection after this value (in milliseconds) */ } esp_mqtt_client_config_t; +/** + * @brief Creates mqtt client handle based on the configuration + * + * @param config mqtt configuration structure + * + * @return mqtt_client_handle if successfully created, NULL on error + */ esp_mqtt_client_handle_t esp_mqtt_client_init(const esp_mqtt_client_config_t *config); + +/** + * @brief Sets mqtt connection URI. This API is usually used to overrides the URI + * configured in esp_mqtt_client_init + * + * @param client mqtt client hanlde + * @param uri + * + * @return ESP_FAIL if URI parse error, ESP_OK on success + */ esp_err_t esp_mqtt_client_set_uri(esp_mqtt_client_handle_t client, const char *uri); + +/** + * @brief Starts mqtt client with already created client handle + * + * @param client mqtt client handle + * + * @return ESP_OK on success + * ESP_ERR_INVALID_ARG on wrong initialization + * ESP_FAIL on other error + */ esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client); + +/** + * @brief This api is typically used to force reconnection upon a specific event + * + * @param client mqtt client handle + * + * @return ESP_OK on success + * ESP_FAIL if client is in invalid state + */ esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client); + +/** + * @brief Stops mqtt client tasks + * + * @param client mqtt client handle + * + * @return ESP_OK on success + * ESP_FAIL if client is in invalid state + */ esp_err_t esp_mqtt_client_stop(esp_mqtt_client_handle_t client); -esp_err_t esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos); -esp_err_t esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic); + +/** + * @brief Subscribe the client to defined topic with defined qos + * + * Notes: + * - Client must be connected to send subscribe message + * - This API is could be executed from a user task or + * from a mqtt event callback i.e. internal mqtt task + * (API is protected by internal mutex, so it might block + * if a longer data receive operation is in progress. + * + * @param client mqtt client handle + * @param topic + * @param qos + * + * @return message_id of the subscribe message on success + * -1 on failure + */ +int esp_mqtt_client_subscribe(esp_mqtt_client_handle_t client, const char *topic, int qos); + +/** + * @brief Unsubscribe the client from defined topic + * + * Notes: + * - Client must be connected to send unsubscribe message + * - It is thread safe, please refer to `esp_mqtt_client_subscribe` for details + * + * @param client mqtt client handle + * @param topic + * + * @return message_id of the subscribe message on success + * -1 on failure + */ +int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *topic); + +/** + * @brief Client to send a publish message to the broker + * + * Notes: + * - Client doesn't have to be connected to send publish message + * (although it would drop all qos=0 messages, qos>1 messages would be enqueued) + * - It is thread safe, please refer to `esp_mqtt_client_subscribe` for details + * + * @param client mqtt client handle + * @param topic topic string + * @param data payload string (set to NULL, sending empty payload message) + * @param len data length, if set to 0, length is calculated from payload string + * @param qos qos of publish message + * @param retain ratain flag + * + * @return message_id of the subscribe message on success + * 0 if cannot publish + */ int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic, const char *data, int len, int qos, int retain); + +/** + * @brief Destroys the client handle + * + * @param client mqtt client handle + * + * @return ESP_OK + */ esp_err_t esp_mqtt_client_destroy(esp_mqtt_client_handle_t client); + +/** + * @brief Set configuration structure, typically used when updating the config (i.e. on "before_connect" event + * + * @param client mqtt client handle + * + * @param config mqtt configuration structure + * + * @return ESP_ERR_NO_MEM if failed to allocate + * ESP_OK on success + */ esp_err_t esp_mqtt_set_config(esp_mqtt_client_handle_t client, const esp_mqtt_client_config_t *config); #ifdef __cplusplus