update documentation example (#7697)

d-a-v · web-flow · commit c919f61169df · 2020-11-10T22:17:17.000+01:00
diff --git a/doc/esp8266wifi/server-examples.rst b/doc/esp8266wifi/server-examples.rst
@@ -39,17 +39,19 @@ Then let's write a short function ``prepareHtmlPage()``, that will return a ``St
 
     String prepareHtmlPage()
     {
-      String htmlPage = 
-         String("HTTP/1.1 200 OK\r\n") +
-                "Content-Type: text/html\r\n" +
-                "Connection: close\r\n" +  // the connection will be closed after completion of the response
-                "Refresh: 5\r\n" +  // refresh the page automatically every 5 sec
-                "\r\n" +
-                "<!DOCTYPE HTML>" +
-                "<html>" +
-                "Analog input:  " + String(analogRead(A0)) +
-                "</html>" +
-                "\r\n";
+      String htmlPage;
+      htmlPage.reserve(1024);               // prevent ram fragmentation
+      htmlPage = F("HTTP/1.1 200 OK\r\n"
+                   "Content-Type: text/html\r\n"
+                   "Connection: close\r\n"  // the connection will be closed after completion of the response
+                   "Refresh: 5\r\n"         // refresh the page automatically every 5 sec
+                   "\r\n"
+                   "<!DOCTYPE HTML>"
+                   "<html>"
+                   "Analog input:  ");
+      htmlPage += analogRead(A0);
+      htmlPage += F("</html>"
+                    "\r\n");
       return htmlPage;
     }
 
@@ -79,7 +81,7 @@ The content contains two basic `HTML <https://www.w3schools.com/html/>`__ tags,
 
 .. code:: cpp
 
-    String(analogRead(A0))
+    analogRead(A0)
 
 The Page is Served
 ~~~~~~~~~~~~~~~~~~
@@ -90,7 +92,7 @@ Serving of this web page will be done in the ``loop()`` where server is waiting
 
     void loop()
     {
-      WiFiClient client = server.available(); 
+      WiFiClient client = server.available();
       if (client)
       {
         // we have a new client sending some request
@@ -126,6 +128,18 @@ The whole process is concluded by stopping the connection with client:
 
     client.stop();
 
+But before that, we must not interrupt client's request:
+
+.. code:: cpp
+
+    while (client.available()) {
+      // but first, let client finish its request
+      // that's diplomatic compliance to protocols
+      // (and otherwise some clients may complain, like curl)
+      // (that is an example, prefer using a proper webserver library)
+      client.read();
+    }
+
 Put it Together
 ~~~~~~~~~~~~~~~
 
@@ -163,24 +177,26 @@ Complete sketch is presented below.
     // prepare a web page to be send to a client (web browser)
     String prepareHtmlPage()
     {
-      String htmlPage = 
-         String("HTTP/1.1 200 OK\r\n") +
-                "Content-Type: text/html\r\n" +
-                "Connection: close\r\n" +  // the connection will be closed after completion of the response
-                "Refresh: 5\r\n" +  // refresh the page automatically every 5 sec
-                "\r\n" +
-                "<!DOCTYPE HTML>" +
-                "<html>" +
-                "Analog input:  " + String(analogRead(A0)) +
-                "</html>" +
-                "\r\n";
+      String htmlPage;
+      htmlPage.reserve(1024);               // prevent ram fragmentation
+      htmlPage = F("HTTP/1.1 200 OK\r\n"
+                   "Content-Type: text/html\r\n"
+                   "Connection: close\r\n"  // the connection will be closed after completion of the response
+                   "Refresh: 5\r\n"         // refresh the page automatically every 5 sec
+                   "\r\n"
+                   "<!DOCTYPE HTML>"
+                   "<html>"
+                   "Analog input:  ");
+      htmlPage += analogRead(A0);
+      htmlPage += F("</html>"
+                    "\r\n");
       return htmlPage;
     }
 
 
     void loop()
     {
-      WiFiClient client = server.available(); 
+      WiFiClient client = server.available();
       // wait for a client (web browser) to connect
       if (client)
       {
@@ -200,7 +216,14 @@ Complete sketch is presented below.
             }
           }
         }
-        delay(1); // give the web browser time to receive the data
+
+        while (client.available()) {
+          // but first, let client finish its request
+          // that's diplomatic compliance to protocols
+          // (and otherwise some clients may complain, like curl)
+          // (that is an example, prefer using a proper webserver library)
+          client.read();
+        }
 
         // close the connection:
         client.stop();
