esp_https_server : Docs and API references fixed

diff --git a/components/esp_http_server/include/esp_http_server.h b/components/esp_http_server/include/esp_http_server.h
index 519538f9ab325b745a65165e3fab2bb497b3d688..990828a1ce2edac0b56bf570a33e738f3f8a6cd9 100644 (file)
--- a/components/esp_http_server/include/esp_http_server.h
+++ b/components/esp_http_server/include/esp_http_server.h
@@ -150,6 +150,10 @@ typedef struct httpd_config {
      * function for freeing the global user context, please specify that here.
      */
     void * global_user_ctx;
+
+    /**
+     * Free function for global user context
+     */
     httpd_free_ctx_fn_t global_user_ctx_free_fn;
 
     /**
@@ -159,6 +163,10 @@ typedef struct httpd_config {
      * It will be freed using free(), unless global_transport_ctx_free_fn is specified.
      */
     void * global_transport_ctx;
+
+    /**
+     * Free function for global transport context
+     */
     httpd_free_ctx_fn_t global_transport_ctx_free_fn;
 
     /**
@@ -570,8 +578,8 @@ esp_err_t httpd_set_pending_override(httpd_req_t *r, httpd_pending_func_t pendin
  *
  * @see httpd_set_send_override()
  *
- * @param[in] hd  HTTPD instance handle
- * @param[in] fd  session socket FD
+ * @param[in] hd        HTTPD instance handle
+ * @param[in] sockfd    Session socket FD
  * @param[in] send_func The send function to be set for this session
  *
  * @return status code
@@ -583,8 +591,8 @@ esp_err_t httpd_set_sess_send_override(httpd_handle_t hd, int sockfd, httpd_send
  *
  * @see httpd_set_recv_override()
  *
- * @param[in] hd  HTTPD instance handle
- * @param[in] fd  session socket FD
+ * @param[in] hd        HTTPD instance handle
+ * @param[in] sockfd    Session socket FD
  * @param[in] recv_func The receive function to be set for this session
  *
  * @return status code
@@ -596,8 +604,8 @@ esp_err_t httpd_set_sess_recv_override(httpd_handle_t hd, int sockfd, httpd_recv
  *
  * @see httpd_set_pending_override()
  *
- * @param[in] hd  HTTPD instance handle
- * @param[in] fd  session socket FD
+ * @param[in] hd           HTTPD instance handle
+ * @param[in] sockfd       Session socket FD
  * @param[in] pending_func The receive function to be set for this session
  *
  * @return status code

diff --git a/components/esp_https_server/README.md b/components/esp_https_server/README.md
deleted file mode 100644 (file)
index 2d7bc7f..0000000
--- a/components/esp_https_server/README.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# HTTPS server
-
-This component is built on top of `esp_http_server`. The HTTPS server takes advantage of hooks and 
-function overrides in the regular HTTP server to provide encryption using OpenSSL. 
-
-All documentation for `esp_http_server` applies also to a server you create this way.
-
-## Used APIs
-
-The following API of `esp_http_server` should not be used with `esp_https_server`, as they are
-used internally to handle secure sessions and to maintain internal state:
-
-- "send", "receive" and "pending" function overrides - secure socket handling
-  - `httpd_set_sess_send_override()`
-  - `httpd_set_sess_recv_override()`
-  - `httpd_set_sess_pending_override()`
-  - `httpd_set_send_override()`
-  - `httpd_set_recv_override()`
-  - `httpd_set_pending_override()`
-- "transport context" - both global and session
-  - `httpd_sess_get_transport_ctx()` - returns SSL used for the session
-  - `httpd_sess_set_transport_ctx()`
-  - `httpd_get_global_transport_ctx()` - returns the shared SSL context
-  - `httpd_config_t.global_transport_ctx`
-  - `httpd_config_t.global_transport_ctx_free_fn`
-  - `httpd_config_t.open_fn` - used to set up secure sockets
-
-Everything else can be used without limitations.
-
-## Usage
-
-Please see the example `protocols/https_server` to learn how to set up a secure server.
-
-Basically all you need is to generate a certificate, embed it in the firmware, and provide
-its pointers and lengths to the start function via the init struct.
-
-The server can be started with or without SSL by changing a flag in the init struct. 
-This could be used e.g. for testing or in trusted environments where you prefer speed over security.
-
-## Performance
-
-The initial session setup can take about two seconds, or more with slower clock speeds or more 
-verbose logging. Subsequent requests through the open secure socket are much faster (down to under
-100 ms).

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 3306fbc070d7deb4e8281ea2bd13f20c864605aa..9e1bcdc9ef117b9db33b528c855b2c191f71eb9a 100644 (file)
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -98,6 +98,7 @@ INPUT = \
     ../../components/mdns/include/mdns.h \
     ../../components/esp_http_client/include/esp_http_client.h \
     ../../components/esp_http_server/include/esp_http_server.h \
+    ../../components/esp_https_server/include/esp_https_server.h \
     ##
     ## Provisioning - API Reference
     ##

diff --git a/docs/en/api-reference/protocols/esp_https_server.rst b/docs/en/api-reference/protocols/esp_https_server.rst
new file mode 100644 (file)
index 0000000..714afec
--- /dev/null
+++ b/docs/en/api-reference/protocols/esp_https_server.rst
@@ -0,0 +1,51 @@
+HTTPS server
+============
+
+Overview
+--------
+
+This component is built on top of `esp_http_server`. The HTTPS server takes advantage of hooks and function overrides in the regular HTTP server to provide encryption using OpenSSL.
+
+All documentation for `esp_http_server` applies also to a server you create this way.
+
+Used APIs
+---------
+
+The following API of `esp_http_server` should not be used with `esp_https_server`, as they are used internally to handle secure sessions and to maintain internal state:
+
+- "send", "receive" and "pending" function overrides - secure socket handling
+  - :cpp:func:`httpd_set_sess_send_override`
+  - :cpp:func:`httpd_set_sess_recv_override`
+  - :cpp:func:`httpd_set_sess_pending_override`
+  - :cpp:func:`httpd_set_send_override`
+  - :cpp:func:`httpd_set_recv_override`
+  - :cpp:func:`httpd_set_pending_override`
+- "transport context" - both global and session
+  - :cpp:func:`httpd_sess_get_transport_ctx` - returns SSL used for the session
+  - :cpp:func:`httpd_sess_set_transport_ctx`
+  - :cpp:func:`httpd_get_global_transport_ctx` - returns the shared SSL context
+  - :c:member:`httpd_config_t.global_transport_ctx`
+  - :c:member:`httpd_config_t.global_transport_ctx_free_fn`
+  - :c:member:`httpd_config_t.open_fn` - used to set up secure sockets
+
+Everything else can be used without limitations.
+
+Usage
+-----
+
+Please see the example :example:`protocols/https_server` to learn how to set up a secure server.
+
+Basically all you need is to generate a certificate, embed it in the firmware, and provide its pointers and lengths to the start function via the init struct.
+
+The server can be started with or without SSL by changing a flag in the init struct. This could be used e.g. for testing or in trusted environments where you prefer speed over security.
+
+Performance
+-----------
+
+The initial session setup can take about two seconds, or more with slower clock speeds or more verbose logging. Subsequent requests through the open secure socket are much faster (down to under
+100 ms).
+
+API Reference
+-------------
+
+.. include:: /_build/inc/esp_https_server.inc

diff --git a/docs/en/api-reference/protocols/index.rst b/docs/en/api-reference/protocols/index.rst
index fff67481f32011a96a55788c2464415ab78a52b2..f57b4cc4e60ef2a78c0aa473107d6d003e83a0c6 100644 (file)
--- a/docs/en/api-reference/protocols/index.rst
+++ b/docs/en/api-reference/protocols/index.rst
@@ -8,6 +8,7 @@ Protocols API
    ESP-TLS <esp_tls>
    HTTP Client <esp_http_client>
    HTTP Server <esp_http_server>
+   HTTPS Server <esp_https_server>
    ASIO <asio>
    ESP-MQTT <mqtt>
    Modbus slave <modbus>

diff --git a/docs/zh_CN/api-reference/protocols/esp_https_server.rst b/docs/zh_CN/api-reference/protocols/esp_https_server.rst
new file mode 100644 (file)
index 0000000..8f338a3
--- /dev/null
+++ b/docs/zh_CN/api-reference/protocols/esp_https_server.rst
@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/protocols/esp_https_server.rst

diff --git a/examples/protocols/https_server/README.md b/examples/protocols/https_server/README.md
index c89c0f79faba1f0287471a9bf8375b26125667a4..08aa770c086c9bd3cfaf3ed31c853de22c8b60c1 100644 (file)
--- a/examples/protocols/https_server/README.md
+++ b/examples/protocols/https_server/README.md
@@ -6,10 +6,19 @@ See the `esp_https_server` component documentation for details.
 
 ## Certificates
 
-You will need to approve a security exception in your browser. This is because of a self signed 
+You will need to approve a security exception in your browser. This is because of a self signed
 certificate; this will be always the case, unless you preload the CA root into your browser/system
 as trusted.
 
-You can generate a new certificate using the OpenSSL command line tool as shown in the script
-`main/certs/gencert.sh`. It is **strongly recommended** to not reuse the example certificate in 
-your application; it is included only for demonstration.
+You can generate a new certificate using the OpenSSL command line tool:
+
+```
+openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -x509 -days 3650 -out cacert.pem -subj "/CN=ESP32 HTTPS server example"
+```
+
+Expiry time and metadata fields can be adjusted in the invocation.
+
+Please see the openssl man pages (man openssl-req) for more details.
+
+It is **strongly recommended** to not reuse the example certificate in your application;
+it is included only for demonstration.

diff --git a/examples/protocols/https_server/main/certs/gencert.sh b/examples/protocols/https_server/main/certs/gencert.sh
deleted file mode 100644 (file)
index 5b2f79d..0000000
--- a/examples/protocols/https_server/main/certs/gencert.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/bin/bash
-
-# Example command to generate a new certificate in the correct format.
-# Expiry time and metadata fields can be adjusted in the invocation.
-
-# Please see the openssl man pages (man openssl-req) for more details
-
-openssl req -newkey rsa:2048 -nodes -keyout prvtkey.pem -x509 -days 3650 -out cacert.pem -subj "/CN=ESP32 HTTPS server example"