various minor web fixes (#8885)

* httpclient: use refs - httpserver: add chunks in examples

* basic https client: update cert

* debug log: read() returning -1 is usual and means "nothing to read"

* emulation on host: SSL server has never been and is now working

* style

* move SSL server certs from examples into a single place with appropriate warnings

* web-hello-servers: make chunks bigger

* factorize template declaration

* http-client: add getString(pre-reservation)

* mock: add umm_info()

* style

* comment API in example

* style

* fix per review

libraries/ESP8266HTTPClient/examples/BasicHttpsClient/BasicHttpsClient.ino

@@ -62,6 +62,7 @@ void loop() {
         // file found at server
         if (httpCode == HTTP_CODE_OK || httpCode == HTTP_CODE_MOVED_PERMANENTLY) {
           String payload = https.getString();
+          // String payload = https.getString(1024);  // optionally pre-reserve string to avoid reallocations in chunk mode
           Serial.println(payload);
         }
       } else {

libraries/ESP8266HTTPClient/src/ESP8266HTTPClient.cpp

@@ -107,7 +107,7 @@ bool HTTPClient::begin(WiFiClient &client, const String& host, uint16_t port, co
         _canReuse = false;
         disconnect(true);
     }
-    
+
     _client = client.clone();
 
     clear();
@@ -483,7 +483,7 @@ int HTTPClient::sendRequest(const char * type, const uint8_t * payload, size_t s
         //
         redirect = false;
         if (
-            _followRedirects != HTTPC_DISABLE_FOLLOW_REDIRECTS && 
+            _followRedirects != HTTPC_DISABLE_FOLLOW_REDIRECTS &&
             redirectCount < _redirectLimit &&
             _location.length() > 0
         ) {
@@ -496,7 +496,7 @@ int HTTPClient::sendRequest(const char * type, const uint8_t * payload, size_t s
                         // (the RFC require user to accept the redirection)
                         _followRedirects == HTTPC_FORCE_FOLLOW_REDIRECTS ||
                         // allow GET and HEAD methods without force
-                        !strcmp(type, "GET") || 
+                        !strcmp(type, "GET") ||
                         !strcmp(type, "HEAD")
                     ) {
                         redirectCount += 1;
@@ -631,7 +631,7 @@ WiFiClient* HTTPClient::getStreamPtr(void)
  * return all payload as String (may need lot of ram or trigger out of memory!)
  * @return String
  */
-const String& HTTPClient::getString(void)
+const String& HTTPClient::getString(int reserve)
 {
     if (_payload) {
         return *_payload;
@@ -639,12 +639,12 @@ const String& HTTPClient::getString(void)
 
     _payload.reset(new StreamString());
 
-    if(_size > 0) {
-        // try to reserve needed memory
-        if(!_payload->reserve((_size + 1))) {
-            DEBUG_HTTPCLIENT("[HTTP-Client][getString] not enough memory to reserve a string! need: %d\n", (_size + 1));
-            return *_payload;
-        }
+    if (_size > 0 && _size > reserve)
+        reserve = _size;
+
+    if (reserve > 0 && !_payload->reserve(reserve)) {
+        DEBUG_HTTPCLIENT("[HTTP-Client][getString] not enough memory to reserve a string! need: %d\n", reserve);
+        return *_payload;
     }
 
     writeToStream(_payload.get());
@@ -732,30 +732,30 @@ void HTTPClient::collectHeaders(const char* headerKeys[], const size_t headerKey
     }
 }
 
-String HTTPClient::header(const char* name)
+const String& HTTPClient::header(const char* name)
 {
     for(size_t i = 0; i < _headerKeysCount; ++i) {
         if(_currentHeaders[i].key == name) {
             return _currentHeaders[i].value;
         }
     }
-    return String();
+    return emptyString;
 }
 
-String HTTPClient::header(size_t i)
+const String& HTTPClient::header(size_t i)
 {
     if(i < _headerKeysCount) {
         return _currentHeaders[i].value;
     }
-    return String();
+    return emptyString;
 }
 
-String HTTPClient::headerName(size_t i)
+const String& HTTPClient::headerName(size_t i)
 {
     if(i < _headerKeysCount) {
         return _currentHeaders[i].key;
     }
-    return String();
+    return emptyString;
 }
 
 int HTTPClient::headers()

libraries/ESP8266HTTPClient/src/ESP8266HTTPClient.h

@@ -203,9 +203,9 @@ public:
 
     /// Response handling
     void collectHeaders(const char* headerKeys[], const size_t headerKeysCount);
-    String header(const char* name);   // get request header value by name
-    String header(size_t i);              // get request header value by number
-    String headerName(size_t i);          // get request header name by number
+    const String& header(const char* name);   // get request header value by name
+    const String& header(size_t i);           // get request header value by number
+    const String& headerName(size_t i);       // get request header name by number
     int headers();                     // get header count
     bool hasHeader(const char* name);  // check if header exists
 
@@ -217,7 +217,13 @@ public:
     WiFiClient* getStreamPtr(void);
     template <typename S> int writeToPrint(S* print) [[deprecated]] { return writeToStream(print); }
     template <typename S> int writeToStream(S* output);
-    const String& getString(void);
+
+    // In case of chunks = when size cannot be known in advance
+    // by the library, it might be useful to pre-reserve enough
+    // space instead of offending memory with a growing String
+    const String& getString() { return getString(0); }
+    const String& getString(int reserve);
+
     static String errorToString(int error);
 
 protected: