Merge branch 'feature/esp_http_client_esp_events' into 'master'

esp_http_client: Add support for esp_events

See merge request espressif/esp-idf!21113

docs/en/api-reference/protocols/esp_http_client.rst

@@ -110,6 +110,33 @@ Examples of Authentication Configuration
                 .auth_type = HTTP_AUTH_TYPE_BASIC,
             };
 
+Event Handling
+--------------
+
+ESP HTTP Client supports event handling by triggering an event handler corresponding to the event which took place.
+:cpp:enum:`esp_http_client_event_id_t` contains all the events which could occur while performing an HTTP request using the ESP HTTP Client.
+
+To enable event handling, you just need to set a callback function using the :cpp:member:`esp_http_client_config_t::event_handler` member.
+
+ESP HTTP Client Diagnostic Information
+--------------------------------------
+Diagnostic information could be helpful to gain insights into a problem. In the case of ESP HTTP Client, this diagnostic information can be collected by registering an event handler with :doc:`the Event Loop library <../system/esp_event>`.
+This feature has been added by keeping in mind the `ESP Insights <https://github.com/espressif/esp-insights>`_ framework which collects the diagnostic information. However, this feature can also be used without any dependency on ESP Insights framework for the diagnostic purpose.
+Event handler can be registered to the event loop using the :cpp:func:`esp_event_handler_register` function.
+
+Expected data types for different HTTP Client events in the event loop:
+
+    - HTTP_EVENT_ERROR            :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_ON_CONNECTED     :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_HEADERS_SENT     :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_ON_HEADER        :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_ON_DATA          :   ``esp_http_client_on_data_t``
+    - HTTP_EVENT_ON_FINISH        :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_DISCONNECTED     :   ``esp_http_client_handle_t``
+    - HTTP_EVENT_REDIRECT         :   ``esp_http_client_redirect_event_data_t``
+
+The :cpp:type:`esp_http_client_handle_t` received along with the event data will be valid until :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` is not received. This handle has been sent primarily to differentiate between different client
+connections and must not be used for any other purpose (as it may change based on client connection state).
 
 API Reference
 -------------