From c3bd5316f773e087d4590b8347447495cf44ac71 Mon Sep 17 00:00:00 2001
From: Suren Gabrielyan <suren.gabrielyan@espressif.com>
Date: Fri, 8 Sep 2023 13:02:28 +0400
Subject: [PATCH] docs(websocket): improve API's header notes

---
 .../esp_websocket_client.c                    | 35 ++++++++++++++++++-
 .../examples/target/main/websocket_example.c  |  3 ++
 .../include/esp_websocket_client.h            | 19 +++++++++-
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/components/esp_websocket_client/esp_websocket_client.c b/components/esp_websocket_client/esp_websocket_client.c
index ef9721125a..aa37fff87e 100644
--- a/components/esp_websocket_client/esp_websocket_client.c
+++ b/components/esp_websocket_client/esp_websocket_client.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -358,6 +358,7 @@ static esp_err_t esp_websocket_client_set_config(esp_websocket_client_handle_t c
     }
     if (config->headers) {
         free(cfg->headers);
+        ESP_LOGI(TAG, "line = %d", __LINE__);
         cfg->headers = strdup(config->headers);
         ESP_WS_CLIENT_MEM_CHECK(TAG, cfg->headers, return ESP_ERR_NO_MEM);
     }
@@ -756,6 +757,38 @@ esp_err_t esp_websocket_client_set_headers(esp_websocket_client_handle_t client,
     return ret;
 }
 
+esp_err_t esp_websocket_client_append_header(esp_websocket_client_handle_t client, const char *key, const char *value)
+{
+    if (client == NULL  || key == NULL || value == NULL) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    websocket_config_storage_t *cfg = client->config;
+    size_t len = strlen(key) + strlen(value) + 3 + 2; // Length for "key: value\r\n"
+
+    if (cfg->headers == NULL) {
+        cfg->headers = (char *)malloc(len);
+        if (cfg->headers == NULL) {
+            return ESP_ERR_NO_MEM;
+        }
+        snprintf(cfg->headers, len, "%s: %s\r\n", key, value);
+        return ESP_OK;
+    }
+
+    char *new_headers;
+    size_t current_len = strlen(cfg->headers);
+    size_t new_len = current_len + len;
+
+    new_headers = (char *)realloc(cfg->headers, new_len);
+    if (new_headers == NULL) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    snprintf(new_headers + current_len, len, "%s: %s\r\n", key, value);
+    cfg->headers = new_headers;
+
+    return ESP_OK;
+}
+
 static esp_err_t esp_websocket_client_recv(esp_websocket_client_handle_t client)
 {
     int rlen;
diff --git a/components/esp_websocket_client/examples/target/main/websocket_example.c b/components/esp_websocket_client/examples/target/main/websocket_example.c
index 4e44f46c97..1886cf8db4 100644
--- a/components/esp_websocket_client/examples/target/main/websocket_example.c
+++ b/components/esp_websocket_client/examples/target/main/websocket_example.c
@@ -141,12 +141,15 @@ static void websocket_app_start(void)
 
 #else
     websocket_cfg.uri = CONFIG_WEBSOCKET_URI;
+    //websocket_cfg.headers = "Sec-WebSocket-Key: my_key\r\nPassword: my_pass\r\n";
 #endif /* CONFIG_WEBSOCKET_URI_FROM_STDIN */
 
     ESP_LOGI(TAG, "Connecting to %s...", websocket_cfg.uri);
 
     esp_websocket_client_handle_t client = esp_websocket_client_init(&websocket_cfg);
     esp_websocket_register_events(client, WEBSOCKET_EVENT_ANY, websocket_event_handler, (void *)client);
+    esp_websocket_client_append_header(client, "Sec-WebSocket-Key", "my_key");
+    esp_websocket_client_append_header(client, "Password", "my_pass");
 
     esp_websocket_client_start(client);
     xTimerStart(shutdown_signal_timer, portMAX_DELAY);
diff --git a/components/esp_websocket_client/include/esp_websocket_client.h b/components/esp_websocket_client/include/esp_websocket_client.h
index 318ae8bc4e..a6fe9094d0 100644
--- a/components/esp_websocket_client/include/esp_websocket_client.h
+++ b/components/esp_websocket_client/include/esp_websocket_client.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -158,6 +158,10 @@ esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, con
  * @brief      Set additional websocket headers for the client, when performing this behavior, the headers will replace the old ones
  * @pre        Must stop the WebSocket client before set headers if the client has been connected
  *
+ *  Notes:
+ *  - To set multiple headers, you can concatenate them in a single line using the "\r\n" symbol.
+ *    Example:  websocket_cfg.headers="Sec-WebSocket-Key: my_key\r\nPassword: my_pass\r\n";
+ *
  * @param[in]  client  The client
  * @param headers  additional header strings each terminated with \r\n
  *
@@ -165,6 +169,19 @@ esp_err_t esp_websocket_client_set_uri(esp_websocket_client_handle_t client, con
  */
 esp_err_t esp_websocket_client_set_headers(esp_websocket_client_handle_t client, const char *headers);
 
+/**
+ * @brief      Appends new key value for to the headers of websocket client
+ *  Notes:
+ *  - This API should be called before websocket client start
+ *
+ * @param[in]  client  The client
+ * @param[in]  key     key which will be appended
+ * @param[in]  value   Value of the key
+ *
+ * @return     esp_err_t
+ */
+esp_err_t esp_websocket_client_append_header(esp_websocket_client_handle_t client, const char *key, const char *value);
+
 /**
  * @brief      Open the WebSocket connection
  *