* 首先调用 :cpp:func:`esp_http_client_init`，创建一个 :cpp:type:`esp_http_client_handle_t` 实例，即基于给定的 :cpp:type:`esp_http_client_config_t` 配置创建 HTTP 客户端句柄。此函数必须第一个被调用。若用户未明确定义参数的配置值，则使用默认值。
* 其次调用 :cpp:func:`esp_http_client_perform`，执行 ``esp_http_client`` 的所有操作，包括打开连接、交换数据、关闭连接（如需要），同时在当前任务完成前阻塞该任务。所有相关的事件（在 :cpp:type:`esp_http_client_config_t` 中指定）将通过事件处理程序被调用。
* 最后调用 :cpp:func:`esp_http_client_cleanup` 来关闭连接（如有），并释放所有分配给 HTTP 客户端实例的内存。此函数必须在操作完成后最后一个被调用。

esp_http_client_config_t cfg = {
    /* other configurations options */
    .use_secure_element = true,
};

为 TLS 使用 ECDSA 外设
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ECDSA 外设可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 **在 ESP-TLS 中使用 ECDSA 外设** 小节。可以按如下方式配置 HTTP 客户端以使用 ECDSA 外设：

.. code-block:: c

    esp_http_client_config_t cfg = {
        /* other configurations options */
        .use_ecdsa_peripheral = true,
        .ecdsa_key_efuse_blk = 4,    // ECDSA 密钥的低 eFuse 块
        .ecdsa_key_efuse_blk_high = 5,   // ECDSA 密钥的高 eFuse 块（仅 SECP384R1）
        .ecdsa_curve = ESP_TLS_ECDSA_CURVE_SECP384R1, // 设置为 ESP_TLS_ECDSA_CURVE_SECP256R1 以使用 SECP256R1 曲线
    };

在发起 HTTPS 请求时，如需服务器验证，首先需要向 ``esp_http_client_config_t`` 配置中的 ``cert_pem`` 成员提供额外的根证书（PEM 格式）。用户还可以通过 ``esp_http_client_config_t`` 配置中的 ``crt_bundle_attach`` 成员，使用 ``ESP x509 Certificate Bundle`` 进行服务器验证。

* :cpp:func:`esp_http_client_init`：创建一个 HTTP 客户端句柄。
* ``esp_http_client_set_*`` 或 ``esp_http_client_delete_*``：修改 HTTP 连接参数（可选）。
* :cpp:func:`esp_http_client_open`：用 ``write_len`` （该参数为需要写入服务器的内容长度）打开 HTTP 连接，设置 ``write_len=0`` 为只读连接。
* :cpp:func:`esp_http_client_write`：向服务器写入数据，最大长度为 :cpp:func:`esp_http_client_open` 函数中的 ``write_len`` 值；配置 ``write_len=0`` 无需调用此函数。
* :cpp:func:`esp_http_client_fetch_headers`：在发送完请求头和服务器数据（如有）后，读取 HTTP 服务器的响应头。从服务器返回 ``content-length``，并可以由 :cpp:func:`esp_http_client_get_status_code` 继承，以获取连接的 HTTP 状态。
* :cpp:func:`esp_http_client_read`：读取 HTTP 流。
* :cpp:func:`esp_http_client_close`：关闭连接。
* :cpp:func:`esp_http_client_cleanup`：释放分配的资源。

* 基于 URI 的认证

    .. highlight:: c

    ::

        esp_http_client_config_t config = {
            .url = "http://user:[email protected]/basic-auth/user/passwd",
            .auth_type = HTTP_AUTH_TYPE_BASIC,
        };


* 基于用户名和密码的认证

    .. highlight:: c

    ::

        esp_http_client_config_t config = {
            .url = "http://httpbin.org/basic-auth/user/passwd",
            .username = "user",
            .password = "passwd",
            .auth_type = HTTP_AUTH_TYPE_BASIC,
        };

* :ref:`CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS`：启用响应头保存（默认禁用以节省内存）。
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`：要保存的响应头的最大数量（默认值：10）。
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`：响应头键和值的最大大小（单位：字节，默认值：各 128 字节）。

#if CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS
esp_http_client_handle_t client = esp_http_client_init(&config);
esp_err_t err = esp_http_client_perform(client);

if (err == ESP_OK) {
    char *content_type = NULL;
    err = esp_http_client_get_response_header(client, "Content-Type", &content_type);
    if (err == ESP_OK && content_type != NULL) {
        ESP_LOGI(TAG, "Content-Type: %s", content_type);
    } else if (err == ESP_ERR_NOT_FOUND) {
        ESP_LOGW(TAG, "Content-Type header not found");
    }

    char *date = NULL;
    err = esp_http_client_get_response_header(client, "Date", &date);
    if (err == ESP_OK && date != NULL) {
        ESP_LOGI(TAG, "Date: %s", date);
    }
}

esp_http_client_cleanup(client);
#endif

* **响应头数量限制**：仅保存前 ``CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`` 个响应头，超出限制的响应头会被丢弃，并产生警告日志。
* **大小限制**：若响应头的键或值长度超过 ``CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`` 字节，该头将被丢弃，并记录包含实际长度的警告日志。
* **多值响应头**：对于在响应中出现多次的响应头（如 ``Set-Cookie``），仅保存最后一次出现的值。
* **大小写敏感性**：查找响应头时不区分大小写，但存储时会保留原始大小写。
* **内存开销**：启用此功能会增加内存消耗。每个客户端实例的近似内存使用量为 ``(CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS * CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE * 2)`` 字节。
* **响应头生命周期**：当通过 :cpp:func:`esp_http_client_perform` 或 :cpp:func:`esp_http_client_prepare` 用同一客户端句柄发起新请求时，保存的响应头会被清空。

返回的头值指针由 HTTP 客户端内部管理，应用程序不得释放该指针。该指针在客户端句柄被清理或启动新请求之前保持有效。

- 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_HEADERS_COMPLETE:   ``esp_http_client_handle_t``
- HTTP_EVENT_ON_STATUS_CODE     :   ``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``

.. code-block:: c

    #include "esp_http_client.h"
    esp_http_client_config_t config = {
        .tls_version = ESP_HTTP_CLIENT_TLS_VER_TLS_1_2,
    };