webserver hook: allow to handle external http protocol (#7459)

* webhook api
* simplify webserver debug printouts, move text to flash
* Hook examples in HelloServer example
* print executable code address in example
* simplify example per @mcspr suggestion

libraries/ESP8266WebServer/examples/HelloServer/HelloServer.ino

@@ -17,7 +17,7 @@ const int led = 13;
 
 void handleRoot() {
   digitalWrite(led, 1);
-  server.send(200, "text/plain", "hello from esp8266!");
+  server.send(200, "text/plain", "hello from esp8266!\r\n");
   digitalWrite(led, 0);
 }
 
@@ -86,6 +86,66 @@ void setup(void) {
 
   server.onNotFound(handleNotFound);
 
+  /////////////////////////////////////////////////////////
+  // Hook examples
+
+  server.addHook([](const String & method, const String & url, WiFiClient * client, ESP8266WebServer::ContentTypeFunction contentType) {
+    (void)method;      // GET, PUT, ...
+    (void)url;         // example: /root/myfile.html
+    (void)client;      // the webserver tcp client connection
+    (void)contentType; // contentType(".html") => "text/html"
+    Serial.printf("A useless web hook has passed\n");
+    Serial.printf("(this hook is in 0x%08x area (401x=IRAM 402x=FLASH))\n", esp_get_program_counter());
+    return ESP8266WebServer::CLIENT_REQUEST_CAN_CONTINUE;
+  });
+
+  server.addHook([](const String&, const String & url, WiFiClient*, ESP8266WebServer::ContentTypeFunction) {
+    if (url.startsWith("/fail")) {
+      Serial.printf("An always failing web hook has been triggered\n");
+      return ESP8266WebServer::CLIENT_MUST_STOP;
+    }
+    return ESP8266WebServer::CLIENT_REQUEST_CAN_CONTINUE;
+  });
+
+  server.addHook([](const String&, const String & url, WiFiClient * client, ESP8266WebServer::ContentTypeFunction) {
+    if (url.startsWith("/dump")) {
+      Serial.printf("The dumper web hook is on the run\n");
+
+      // Here the request is not interpreted, so we cannot for sure
+      // swallow the exact amount matching the full request+content,
+      // hence the tcp connection cannot be handled anymore by the
+      // webserver.
+#ifdef STREAMTO_API
+      // we are lucky
+      client->toWithTimeout(Serial, 500);
+#else
+      auto last = millis();
+      while ((millis() - last) < 500) {
+        char buf[32];
+        size_t len = client->read((uint8_t*)buf, sizeof(buf));
+        if (len > 0) {
+          Serial.printf("(<%d> chars)", (int)len);
+          Serial.write(buf, len);
+          last = millis();
+        }
+      }
+#endif
+      // Two choices: return MUST STOP and webserver will close it
+      //                       (we already have the example with '/fail' hook)
+      // or                  IS GIVEN and webserver will forget it
+      // trying with IS GIVEN and storing it on a dumb WiFiClient.
+      // check the client connection: it should not immediately be closed
+      // (make another '/dump' one to close the first)
+      Serial.printf("\nTelling server to forget this connection\n");
+      static WiFiClient forgetme = *client; // stop previous one if present and transfer client refcounter
+      return ESP8266WebServer::CLIENT_IS_GIVEN;
+    }
+    return ESP8266WebServer::CLIENT_REQUEST_CAN_CONTINUE;
+  });
+
+  // Hook examples
+  /////////////////////////////////////////////////////////
+
   server.begin();
   Serial.println("HTTP server started");
 }