Merge branch 'docs/add_header_files_http_server_code_example' into 'master'

docs: add a note on required header files for the esp_http_server example

See merge request espressif/esp-idf!34389

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

@@ -15,104 +15,9 @@ The HTTP Server component provides an ability for running a lightweight web serv
 Application Examples
 --------------------
 
-    .. code-block:: c
+- :example:`protocols/http_server/simple` demonstrates how to handle arbitrary content lengths, read request headers and URL query parameters, and set response headers.
-
-        /* Our URI handler function to be called during GET /uri request */
-        esp_err_t get_handler(httpd_req_t *req)
-        {
-            /* Send a simple response */
-            const char resp[] = "URI GET Response";
-            httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
-            return ESP_OK;
-        }
-
-        /* Our URI handler function to be called during POST /uri request */
-        esp_err_t post_handler(httpd_req_t *req)
-        {
-            /* Destination buffer for content of HTTP POST request.
-             * httpd_req_recv() accepts char* only, but content could
-             * as well be any binary data (needs type casting).
-             * In case of string data, null termination will be absent, and
-             * content length would give length of string */
-            char content[100];
-
-            /* Truncate if content length larger than the buffer */
-            size_t recv_size = MIN(req->content_len, sizeof(content));
-
-            int ret = httpd_req_recv(req, content, recv_size);
-            if (ret <= 0) {  /* 0 return value indicates connection closed */
-                /* Check if timeout occurred */
-                if (ret == HTTPD_SOCK_ERR_TIMEOUT) {
-                    /* In case of timeout one can choose to retry calling
-                     * httpd_req_recv(), but to keep it simple, here we
-                     * respond with an HTTP 408 (Request Timeout) error */
-                    httpd_resp_send_408(req);
-                }
-                /* In case of error, returning ESP_FAIL will
-                 * ensure that the underlying socket is closed */
-                return ESP_FAIL;
-            }
-
-            /* Send a simple response */
-            const char resp[] = "URI POST Response";
-            httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
-            return ESP_OK;
-        }
-
-        /* URI handler structure for GET /uri */
-        httpd_uri_t uri_get = {
-            .uri      = "/uri",
-            .method   = HTTP_GET,
-            .handler  = get_handler,
-            .user_ctx = NULL
-        };
-
-        /* URI handler structure for POST /uri */
-        httpd_uri_t uri_post = {
-            .uri      = "/uri",
-            .method   = HTTP_POST,
-            .handler  = post_handler,
-            .user_ctx = NULL
-        };
-
-        /* Function for starting the webserver */
-        httpd_handle_t start_webserver(void)
-        {
-            /* Generate default configuration */
-            httpd_config_t config = HTTPD_DEFAULT_CONFIG();
-
-            /* Empty handle to esp_http_server */
-            httpd_handle_t server = NULL;
-
-            /* Start the httpd server */
-            if (httpd_start(&server, &config) == ESP_OK) {
-                /* Register URI handlers */
-                httpd_register_uri_handler(server, &uri_get);
-                httpd_register_uri_handler(server, &uri_post);
-            }
-            /* If server failed to start, handle will be NULL */
-            return server;
-        }
-
-        /* Function for stopping the webserver */
-        void stop_webserver(httpd_handle_t server)
-        {
-            if (server) {
-                /* Stop the httpd server */
-                httpd_stop(server);
-            }
-        }
-
-Simple HTTP Server Example
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-: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.
 
+- :example:`protocols/http_server/advanced_tests` demonstrates how to use the HTTP server for advanced testing.
 
 Persistent Connections
 ----------------------

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

@@ -15,104 +15,9 @@ HTTP Server 组件提供了在 ESP32 上运行轻量级 Web 服务器的功能
 应用示例
 --------
 
-    .. code-block:: c
+- :example:`protocols/http_server/simple` 演示了如何处理任意内容长度的数据，读取请求头和 URL 查询参数，并设置响应头。
-
-        /* URI 处理函数，在客户端发起 GET /uri 请求时被调用 */
-        esp_err_t get_handler(httpd_req_t *req)
-        {
-            /* 发送回简单的响应数据包 */
-            const char resp[] = "URI GET Response";
-            httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
-            return ESP_OK;
-        }
-
-        /* URI 处理函数，在客户端发起 POST/uri 请求时被调用 */
-        esp_err_t post_handler(httpd_req_t *req)
-        {
-            /* 定义 HTTP POST 请求数据的目标缓存区
-             * httpd_req_recv() 只接收 char* 数据，但也可以是
-             * 任意二进制数据（需要类型转换）
-             * 对于字符串数据，null 终止符会被省略，
-             * content_len 会给出字符串的长度 */
-            char content[100];
-
-            /* 如果内容长度大于缓冲区则截断 */
-            size_t recv_size = MIN(req->content_len, sizeof(content));
-
-            int ret = httpd_req_recv(req, content, recv_size);
-            if (ret <= 0) {  /* 返回 0 表示连接已关闭 */
-                /* 检查是否超时 */
-                if (ret == HTTPD_SOCK_ERR_TIMEOUT) {
-                    /* 如果是超时，可以调用 httpd_req_recv() 重试
-                     * 简单起见，这里我们直接
-                     * 响应 HTTP 408（请求超时）错误给客户端 */
-                    httpd_resp_send_408(req);
-                }
-                /* 如果发生了错误，返回 ESP_FAIL 可以确保
-                 * 底层套接字被关闭 */
-                return ESP_FAIL;
-            }
-
-            /* 发送简单的响应数据包 */
-            const char resp[] = "URI POST Response";
-            httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
-            return ESP_OK;
-        }
-
-        /* GET /uri 的 URI 处理结构 */
-        httpd_uri_t uri_get = {
-            .uri      = "/uri",
-            .method   = HTTP_GET,
-            .handler  = get_handler,
-            .user_ctx = NULL
-        };
-
-        /* POST/uri 的 URI 处理结构 */
-        httpd_uri_t uri_post = {
-            .uri      = "/uri",
-            .method   = HTTP_POST,
-            .handler  = post_handler,
-            .user_ctx = NULL
-        };
-
-        /* 启动 Web 服务器的函数 */
-        httpd_handle_t start_webserver(void)
-        {
-            /* 生成默认的配置参数 */
-            httpd_config_t config = HTTPD_DEFAULT_CONFIG();
-
-            /* 置空 esp_http_server 的实例句柄 */
-            httpd_handle_t server = NULL;
-
-            /* 启动 httpd server */
-            if (httpd_start(&server, &config) == ESP_OK) {
-                /* 注册 URI 处理程序 */
-                httpd_register_uri_handler(server, &uri_get);
-                httpd_register_uri_handler(server, &uri_post);
-            }
-            /* 如果服务器启动失败，返回的句柄是 NULL */
-            return server;
-        }
-
-        /* 停止 Web 服务器的函数 */
-        void stop_webserver(httpd_handle_t server)
-        {
-            if (server) {
-                /* 停止 httpd server */
-                httpd_stop(server);
-            }
-        }
-
-简单 HTTP 服务器示例
-^^^^^^^^^^^^^^^^^^^^
-
-:example:`protocols/http_server/simple` 演示了如何处理任意内容长度的数据，读取请求头和 URL 查询参数，并设置响应头。
-
-高级测试示例
-^^^^^^^^^^^^
-
-:example:`protocols/http_server/advanced_tests` 演示了如何使用 HTTP 服务器进行高级测试。
 
+- :example:`protocols/http_server/advanced_tests` 演示了如何使用 HTTP 服务器进行高级测试。
 
 HTTP 长连接
 -----------