IDF release/v3.3 (#3672)

ESP-IDF release/v3.3: 66d3783c8
esp-face: 420fc7e
esp32-camera: 0107093

tools/sdk/include/mqtt/mqtt_client.h

@@ -14,6 +14,9 @@
 
 #include "mqtt_config.h"
 #include "esp_event.h"
+#if CONFIG_ESP_TLS_USE_DS_PERIPHERAL
+#include "rsa_sign_alt.h"
+#endif
 
 #ifdef __cplusplus
 extern "C" {
@@ -37,6 +40,7 @@ typedef struct esp_mqtt_client *esp_mqtt_client_handle_t;
  *
  */
 typedef enum {
+    MQTT_EVENT_ANY = -1,
     MQTT_EVENT_ERROR = 0,          /*!< on error event, additional context: connection return code, error handle from esp_tls (if supported) */
     MQTT_EVENT_CONNECTED,          /*!< connected event, additional context: session_present flag */
     MQTT_EVENT_DISCONNECTED,       /*!< disconnected event */
@@ -88,6 +92,15 @@ typedef enum {
     MQTT_TRANSPORT_OVER_WSS       /*!< MQTT over Websocket Secure, using scheme: ``wss`` */
 } esp_mqtt_transport_t;
 
+/**
+ *  MQTT protocol version used for connection
+ */
+typedef enum {
+    MQTT_PROTOCOL_UNDEFINED = 0,
+    MQTT_PROTOCOL_V_3_1,
+    MQTT_PROTOCOL_V_3_1_1
+} esp_mqtt_protocol_ver_t;
+
 /**
  * @brief MQTT error code structure to be passed as a contextual information into ERROR event
  *
@@ -155,7 +168,7 @@ typedef struct {
     void *user_context;                     /*!< pass user context to this option, then can receive that context in ``event->user_context`` */
     int task_prio;                          /*!< MQTT task priority, default is 5, can be changed in ``make menuconfig`` */
     int task_stack;                         /*!< MQTT task stack size, default is 6144 bytes, can be changed in ``make menuconfig`` */
-    int buffer_size;                        /*!< size of MQTT send/receive buffer, default is 1024 */
+    int buffer_size;                        /*!< size of MQTT send/receive buffer, default is 1024 (only receive buffer size if ``out_buffer_size`` defined) */
     const char *cert_pem;                   /*!< Pointer to certificate data in PEM or DER format for server verify (with SSL), default is NULL, not required to verify the server. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in cert_len. */
     size_t cert_len;                        /*!< Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem */
     const char *client_cert_pem;            /*!< Pointer to certificate data in PEM or DER format for SSL mutual authentication, default is NULL, not required if mutual authentication is not needed. If it is not NULL, also `client_key_pem` has to be provided. PEM-format must have a terminating NULL-character. DER-format requires the length to be passed in client_cert_len. */
@@ -166,6 +179,15 @@ typedef struct {
     int refresh_connection_after_ms;        /*!< Refresh connection after this value (in milliseconds) */
     const struct psk_key_hint* psk_hint_key;     /*!< Pointer to PSK struct defined in esp_tls.h to enable PSK authentication (as alternative to certificate verification). If not NULL and server/client certificates are NULL, PSK is enabled */
     bool          use_global_ca_store;      /*!< Use a global ca_store for all the connections in which this bool is set. */
+    int reconnect_timeout_ms;               /*!< Reconnect to the broker after this value in miliseconds if auto reconnect is not disabled */
+    const char **alpn_protos;               /*!< NULL-terminated list of supported application protocols to be used for ALPN */
+    const char *clientkey_password;         /*!< Client key decryption password string */
+    int clientkey_password_len;             /*!< String length of the password pointed to by clientkey_password */
+    esp_mqtt_protocol_ver_t protocol_ver;   /*!< MQTT protocol version used for connection, defaults to value from menuconfig*/
+    int out_buffer_size;                    /*!< size of MQTT output buffer. If not defined, both output and input buffers have the same size defined as ``buffer_size`` */
+    bool skip_cert_common_name_check;       /*!< Skip any validation of server certificate CN field, this reduces the security of TLS and makes the mqtt client susceptible to MITM attacks  */
+    bool use_secure_element;                /*!< enable secure element for enabling SSL connection */
+    void *ds_data;                          /*!< carrier of handle for digital signature parameters */
 } esp_mqtt_client_config_t;
 
 /**
@@ -209,9 +231,21 @@ esp_err_t esp_mqtt_client_start(esp_mqtt_client_handle_t client);
  */
 esp_err_t esp_mqtt_client_reconnect(esp_mqtt_client_handle_t client);
 
+/**
+ * @brief This api is typically used to force disconnection from the broker
+ *
+ * @param client    mqtt client handle
+ *
+ * @return ESP_OK on success
+ */
+esp_err_t esp_mqtt_client_disconnect(esp_mqtt_client_handle_t client);
+
 /**
  * @brief Stops mqtt client tasks
  *
+ *  * Notes:
+ *  - Cannot be called from the mqtt event handler
+ *
  * @param client    mqtt client handle
  *
  * @return ESP_OK on success
@@ -257,6 +291,9 @@ int esp_mqtt_client_unsubscribe(esp_mqtt_client_handle_t client, const char *top
  * @brief Client to send a publish message to the broker
  *
  * Notes:
+ * - This API might block for several seconds, either due to network timeout (10s)
+ *   or if publishing payloads longer than internal buffer (due to message
+ *   fragmentation)
  * - 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
@@ -276,6 +313,9 @@ int esp_mqtt_client_publish(esp_mqtt_client_handle_t client, const char *topic,
 /**
  * @brief Destroys the client handle
  *
+ * Notes:
+ *  - Cannot be called from the mqtt event handler
+ *
  * @param client    mqtt client handle
  *
  * @return ESP_OK