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

2024-09-20 15:08:41 +08:00
parent 1ac6043bce
commit ef9cfa5998
12 changed files with 93 additions and 25 deletions
@@ -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 参考
 ----------
@@ -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 基本请求
@@ -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 参考
 --------

@@ -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 参考
 ---------

@@ -178,7 +178,7 @@ ESP 本地控制
        }


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

 客户端实现
 --------------
@@ -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 连接。


 其他选项