Merge branch 'docs/update_application_example_http_server' into 'master'

docs: update application examples for esp_http_server.rst, esp_https_server.rst, and mbedtls.rst

See merge request espressif/esp-idf!33676

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

@@ -84,11 +84,11 @@ The bundle is kept updated by periodic sync with the Mozilla's NSS root certific
 Application Examples
 --------------------
 
-Simple HTTPS example that uses ESP-TLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification: :example:`protocols/https_x509_bundle`.
+- :example:`protocols/https_x509_bundle` demonstrates how to use ESP-TLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification.
 
-HTTPS example that uses ESP-TLS and the default bundle: :example:`protocols/https_request`.
+- :example:`protocols/https_request` demonstrates an HTTPS example that uses ESP-TLS and the default bundle.
 
-HTTPS example that uses mbedTLS and the default bundle: :example:`protocols/https_mbedtls`.
+- :example:`protocols/https_mbedtls` demonstrates an HTTPS example that uses Mbed TLS and the default bundle.
 
 API Reference
 -------------

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

@@ -13,10 +13,10 @@ Overview
     * :cpp:func:`esp_http_client_cleanup`: Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.
 
 
-Application Example
--------------------
+Application Examples
+--------------------
 
-Simple example that uses ESP HTTP Client to make HTTP/S requests can be found at :example:`protocols/esp_http_client`.
+- :example:`protocols/esp_http_client` demonstrates how to use the ESP HTTP Client to make HTTP/S requests.
 
 
 Basic HTTP Request

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

@@ -12,8 +12,8 @@ The HTTP Server component provides an ability for running a lightweight web serv
     * :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task closes all open connections, removes registered URI handlers and resets all session context data to empty.
     * :cpp:func:`httpd_register_uri_handler`: A URI handler is registered by passing object of type ``httpd_uri_t`` structure which has members including ``uri`` name, ``method`` type (eg. ``HTTPD_GET/HTTPD_POST/HTTPD_PUT`` etc.), function pointer of type ``esp_err_t *handler (httpd_req_t *req)`` and ``user_ctx`` pointer to user context data.
 
-Application Example
--------------------
+Application Examples
+--------------------
 
     .. code-block:: c
 
@@ -106,7 +106,12 @@ Application Example
 Simple HTTP Server Example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Check HTTP server example under :example:`protocols/http_server/simple` where handling of arbitrary content lengths, reading request headers and URL query parameters, and setting response headers is demonstrated.
+:example:`protocols/http_server/simple` demonstrates how to handle arbitrary content lengths, read request headers and URL query parameters, and set response headers.
+
+Advanced Testing Example
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+:example:`protocols/http_server/advanced_tests` demonstrates how to use the HTTP server for advanced testing.
 
 
 Persistent Connections
@@ -146,13 +151,15 @@ Persistent Connections Example
     }
 
 
-Check the example under :example:`protocols/http_server/persistent_sockets`.
+Check the example under :example:`protocols/http_server/persistent_sockets`. This example demonstrates how to set up and use an HTTP server with persistent sockets, allowing for independent sessions or contexts per client.
 
 
-Websocket Server
+WebSocket Server
 ----------------
 
-The HTTP server component provides websocket support. The websocket feature can be enabled in menuconfig using the :ref:`CONFIG_HTTPD_WS_SUPPORT` option. Please refer to the :example:`protocols/http_server/ws_echo_server` example which demonstrates usage of the websocket feature.
+The HTTP server component provides WebSocket support. The WebSocket feature can be enabled in menuconfig using the :ref:`CONFIG_HTTPD_WS_SUPPORT` option.
+
+:example:`protocols/http_server/ws_echo_server` demonstrates how to create a WebSocket echo server using the HTTP server, which starts on a local network and requires a WebSocket client for interaction, echoing back received WebSocket frames.
 
 
 Event Handling
@@ -174,6 +181,26 @@ Expected data type for different ESP HTTP server events in event loop:
     - HTTP_SERVER_EVENT_DISCONNECTED    :   ``int``
     - HTTP_SERVER_EVENT_STOP            :   ``NULL``
 
+File Serving
+------------
+
+:example:`protocols/http_server/file_serving` demonstrates how to create a simple HTTP file server, with both upload and download capabilities.
+
+Captive Portal
+--------------
+
+:example:`protocols/http_server/captive_portal` demonstrates two methods of creating a captive portal, which directs users to an authentication page before browsing, using either DNS queries and HTTP requests redirection or a modern method involving a field in the DHCP offer.
+
+Asynchronous Handlers
+---------------------
+
+:example:`protocols/http_server/async_handlers` demonstrates how to handle multiple long-running simultaneous requests within the HTTP server, using different URIs for asynchronous requests, quick requests, and the index page.
+
+RESTful API
+-----------
+
+:example:`protocols/http_server/restful_server` demonstrates how to implement a RESTful API server and HTTP server, with a frontend browser UI, and designs several APIs to fetch resources, using mDNS to parse the domain name, and deploying the webpage to host PC via semihost technology or to SPI flash or SD Card.
+
 API Reference
 -------------
 

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

@@ -63,6 +63,13 @@ Expected data type for different ESP HTTPS server events in event loop:
     - HTTPS_SERVER_EVENT_DISCONNECTED   :   ``NULL``
     - HTTPS_SERVER_EVENT_STOP           :   ``NULL``
 
+Application Examples
+--------------------
+
+- :example:`protocols/https_server/simple` demonstrates how to create an HTTPS server that returns a simple HTML page when visited.
+
+- :example:`protocols/https_server/wss_server` demonstrates how to create an SSL server with a simple WebSocket request handler that supports handling multiple clients, PING-PONG mechanism, and sending asynchronous messages to all clients.
+
 API Reference
 -------------
 

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

@@ -103,7 +103,7 @@ You may set security for transport in ESP local control using following options:
 Creating a Property
 -------------------
 
-Now that we know how to start the **esp_local_ctrl** service, let's add a property to it. Each property must have a unique ```name``` (string), a ``type`` (e.g., enum), ``flags``` (bit fields) and ``size```.
+Now that we know how to start the **esp_local_ctrl** service, let's add a property to it. Each property must have a unique ``name`` (string), a ``type`` (e.g., enum), ``flags`` (bit fields) and ``size``.
 
 The ``size`` is to be kept 0, if we want our property value to be of variable length (e.g., if it is a string or bytestream). For data types with fixed-length property value, like int, float, etc., setting the ``size`` field to the right value helps **esp_local_ctrl** to perform internal checks on arguments received with write requests.
 
@@ -178,7 +178,7 @@ Here is an example of ``set_prop_values()`` handler. Notice how we restrict from
         }
 
 
-For complete example see :example:`protocols/esp_local_ctrl`.
+For complete example see :example:`protocols/esp_local_ctrl`. The example demonstrates how to set up a secure ``esp_local_ctrl`` service over HTTPS transport for controlling devices on a local network.
 
 Client Side Implementation
 --------------------------

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

@@ -45,7 +45,7 @@ Examples in ESP-IDF use :doc:`/api-reference/protocols/esp_tls` which provides a
 
 Refer to the examples :example:`protocols/https_server/simple` (Simple HTTPS server) and :example:`protocols/https_request` (Make HTTPS requests) for more information.
 
-If the Mbed TLS API is to be used directly, refer to the example :example:`protocols/https_mbedtls`.
+If you plan to use the Mbed TLS API directly, refer to the example :example:`protocols/https_mbedtls`. This example demonstrates how to establish an HTTPS connection using Mbed TLS by setting up a secure socket with a certificate bundle for verification.
 
 
 Alternatives

docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst

@@ -84,11 +84,11 @@ ESP x509 证书包 API 提供了一种简便的方法，帮助你安装自定义
 应用示例
 ---------
 
-使用 ESP-TLS 创建安全套接字连接的简单 HTTPS 示例：:example:`protocols/https_x509_bundle`，该示例使用了证书包并添加了两个自定义证书用于验证。
+:example:`protocols/https_x509_bundle` 演示了如何使用 ESP-TLS 创建安全套接字连接的简单 HTTPS 示例，该示例使用了证书包并添加了两个自定义证书用于验证。
 
-使用 ESP-TLS 和默认证书包的 HTTPS 示例：:example:`protocols/https_request`。
+:example:`protocols/https_request` 演示了如何使用 ESP-TLS 和默认证书包的 HTTPS 示例。
 
-使用 mbedTLS 和默认证书包的 HTTPS 示例：:example:`protocols/https_mbedtls`。
+:example:`protocols/https_mbedtls` 演示了如何使用 Mbed TLS 和默认证书包的 HTTPS 示例。
 
 API 参考
 ----------

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

@@ -16,7 +16,7 @@ ESP HTTP 客户端
 应用示例
 --------
 
-使用 ESP HTTP 客户端发起 HTTP/S 请求的简单示例，可参考 :example:`protocols/esp_http_client`。
+:example:`protocols/esp_http_client` 演示了如何使用 ESP HTTP 客户端发起 HTTP/S 请求。
 
 
 HTTP 基本请求

docs/zh_CN/api-reference/protocols/esp_http_server.rst

@@ -106,7 +106,12 @@ HTTP Server 组件提供了在 ESP32 上运行轻量级 Web 服务器的功能
 简单 HTTP 服务器示例
 ^^^^^^^^^^^^^^^^^^^^
 
-请查看位于 :example:`protocols/http_server/simple` 的 HTTP 服务器示例，该示例演示了如何处理任意内容长度的数据，读取请求头和 URL 查询参数，设置响应头。
+:example:`protocols/http_server/simple` 演示了如何处理任意内容长度的数据，读取请求头和 URL 查询参数，并设置响应头。
+
+高级测试示例
+^^^^^^^^^^^^
+
+:example:`protocols/http_server/advanced_tests` 演示了如何使用 HTTP 服务器进行高级测试。
 
 
 HTTP 长连接
@@ -146,13 +151,15 @@ HTTP 服务器具有长连接的功能，允许重复使用同一个连接（会
     }
 
 
-详情请参考位于 :example:`protocols/http_server/persistent_sockets` 的示例代码。
+详情请参考位于 :example:`protocols/http_server/persistent_sockets` 的示例代码。该示例演示了如何设置和使用带有持久套接字的 HTTP 服务器，允许每个客户端拥有独立的会话或上下文。
 
 
-Websocket 服务器
+WebSocket 服务器
 ----------------
 
-HTTP 服务器组件提供 websocket 支持。可以在 menuconfig 中使用 :ref:`CONFIG_HTTPD_WS_SUPPORT` 选项启用 websocket 功能。有关如何使用 websocket 功能，请参阅 :example:`protocols/http_server/ws_echo_server` 目录下的示例代码。
+HTTP 服务器组件提供 websocket 支持。可以在 menuconfig 中使用 :ref:`CONFIG_HTTPD_WS_SUPPORT` 选项启用 websocket 功能。
+
+:example:`protocols/http_server/ws_echo_server` 演示了如何使用 HTTP 服务器创建一个 WebSocket 回显服务器，该服务器在本地网络上启动，与 WebSocket 客户端进行交互，回显接收到的 WebSocket 帧。
 
 
 事件处理
@@ -174,6 +181,26 @@ ESP HTTP 服务器有各种事件，当特定事件发生时，:doc:`事件循
     - HTTP_SERVER_EVENT_DISCONNECTED    :   ``int``
     - HTTP_SERVER_EVENT_STOP            :   ``NULL``
 
+文件服务
+------------
+
+:example:`protocols/http_server/file_serving` 演示了如何创建一个简单的 HTTP 文件服务器，支持文件上传和下载功能。
+
+强制网络门户
+-----------------
+
+:example:`protocols/http_server/captive_portal` 演示了创建强制网络门户的两种方法，用户在浏览前会被引导到一个认证页面。这两种方法分别使用 DNS 查询和 HTTP 请求重定向，或通过 DHCP offer 中的字段来实现。
+
+异步处理程序
+---------------------
+
+:example:`protocols/http_server/async_handlers` 演示了如何在 HTTP 服务器中处理多个长时间运行的并发请求，使用不同的 URI 来处理异步请求、快速请求以及主页请求。
+
+RESTful API
+-----------
+
+:example:`protocols/http_server/restful_server` 演示了如何实现 RESTful API 服务器和 HTTP 服务器，并结合前端浏览器 UI，设计了多个 API 来获取资源，使用 mDNS 解析域名，并通过半主机技术将网页部署到主机 PC、SPI flash 或 SD 卡上。
+
 API 参考
 --------
 

docs/zh_CN/api-reference/protocols/esp_https_server.rst

@@ -63,6 +63,13 @@ ESP HTTPS 服务器在特定事件发生时，可以通过 :doc:`../system/esp_e
     - HTTPS_SERVER_EVENT_DISCONNECTED   :   ``NULL``
     - HTTPS_SERVER_EVENT_STOP           :   ``NULL``
 
+应用示例
+--------------------
+
+- :example:`protocols/https_server/simple` 演示了如何创建一个 HTTPS 服务器，当访问时返回一个简单的 HTML 页面。
+
+- :example:`protocols/https_server/wss_server` 演示了如何创建一个支持多客户端的 SSL 服务器，具备简单的 WebSocket 请求处理器、PING-PONG 机制，并能够向所有客户端发送异步消息。
+
 API 参考
 ---------
 

docs/zh_CN/api-reference/protocols/esp_local_ctrl.rst

@@ -178,7 +178,7 @@ ESP 本地控制
         }
 
 
-完整示例请参见 :example:`protocols/esp_local_ctrl`。
+完整示例请参见 :example:`protocols/esp_local_ctrl`。该示例演示了如何通过 HTTPS 传输设置一个安全的 ``esp_local_ctrl`` 服务，以便在本地网络中控制设备。
 
 客户端实现
 --------------

docs/zh_CN/api-reference/protocols/mbedtls.rst

@@ -45,7 +45,7 @@ ESP-IDF 中的示例使用 :doc:`/api-reference/protocols/esp_tls`，为访问
 
 参考示例 :example:`protocols/https_server/simple` （简单的 HTTPS 服务器）和 :example:`protocols/https_request` （发出 HTTPS 请求）了解更多信息。
 
-如需直接使用 Mbed TLS API，请参考示例 :example:`protocols/https_mbedtls`。
+如需直接使用 Mbed TLS API，请参考示例 :example:`protocols/https_mbedtls`。该示例演示了如何通过 Mbed TLS 设置安全套接字，并使用证书包进行验证，从而建立 HTTPS 连接。
 
 
 其他选项