comments

d-a-v · d-a-v · commit 474d5a130605 · 2020-01-01T18:54:29.000+01:00
diff --git a/cores/esp8266/Stream.h b/cores/esp8266/Stream.h
@@ -109,62 +109,94 @@ class Stream: public Print {
         virtual String readString();
         String readStringUntil(char terminator);
 
-        // ::read(buf, len): conflicting returned type:
+        //////////////////// extension: readNow (is ::read() with unified signature)
+        // (supposed to be internally used, and ephemeral)
+        //
+        // about ::read(buf, len): conflicting returned type:
         // - `int` in arduino's Client::
         // - `size_t` in esp8266 API (HardwareSerial::, FS::)
         // - not existent in arduino's Stream::
         // changing every read()/write() `size_t` return type to `int` will be a breaking change
         // => adding int ::readNow(buf, len) for now (following official `int Client::read(buf, len))`
         //
         // int ::readNow(buf, len)
-        // read at most len bytes, returns effectively transfered bytes (can be less than len)
-        // immediate return when no more data are available (no timeout)
-        virtual int readNow(char* buffer, size_t len);
-        virtual int readNow(uint8_t* buffer, size_t len) final { return readNow((char*)buffer, len); }
+        // read at most len bytes, returns effectively transfered bytes (can be less than 'len')
+        // with no timeout: immediate return when no more data are available
+        virtual int readNow (char* buffer, size_t len);
+        virtual int readNow (uint8_t* buffer, size_t len) final { return readNow((char*)buffer, len); }
 
-        //////////////////// extensions: direct access to input buffer
+        //////////////////// extension: direct access to input buffer
+        // for providing, when possible, a pointer to available data for read
 
-        // inform user and ::to() on effective buffered peek API implementation
+        // informs user and ::to() on effective buffered peek API implementation
+        // by default: not available
         virtual bool peekBufferAPI () const { return false; }
 
-        // return number of byte accessible by peekBuffer()
+        // returns number of byte accessible by peekBuffer()
         virtual size_t availableForPeek () { return 0; }
 
-        // return a pointer to available data buffer (size = availableForPeek())
-        // semantic forbids any kind of read()
-        //     after calling peekBuffer()
-        //     and before calling peekConsume()
+        // returns a pointer to available data buffer (size = availableForPeek())
+        // semantic forbids any kind of ::read()
+        //     - after calling peekBuffer()
+        //     - and before calling peekConsume()
         virtual const char* peekBuffer () { return nullptr; }
 
-        // consume bytes after peekBuffer() use
+        // consumes bytes after peekBuffer() use
+        // (then ::read() is allowed)
         virtual void peekConsume (size_t consume) { (void)consume; }
 
         // by default read timeout is possible (incoming data from network,serial..)
-        // (children can override to false (like String))
+        // children can override to false (like String::)
+        // (outputTimeoutPossible() is defined in Print::)
         virtual bool inputTimeoutPossible () const { return true; }
 
         //////////////////// extensions: Stream streams
-
         // Stream::to()
-        // transfer from `Stream::` to `Print::` at most maxlen bytes and return number of transfered bytes
-        // (uses 1-copy peekBuffer API when available, or transfer through a 2-copies local stack space)
-        // - maxLen<0 will transfer until input starvation or saturated output
-        // - timeout_ms==TimeoutMs::neverExpires: use getTimeout() (when 0: take what's available and immediate return)
-        // - readUntilChar: setting anything in 0..255 will stop transfer when this char is read *and copied too*.
+        //
+        // Stream::to() uses 1-copy transfers when peekBuffer API is
+        // available, or makes a regular transfer through a local temporary
+        // stack buffer.
+        //
+        // By default "source->to(&dest)" transfers everything until
+        // available (read or write) gets to 0 and a timeout occurs.
+        //
+        // "source->to(&dest, maxLen)" is like above but also returns when
+        // maxLen bytes are transferred.
+        //
+        // More generally ::to() will transfer as much as possible until:
+        //      - maxLen (>=0) bytes are transferred           (without timeout),
+        //      - or readUntilChar (>=0) is reached            (without timeout),
+        //      - or available for read or write gets to zero  (after timeout).
+        //
+        // Timeout value is by default thisStream->getTimeout() but it can
+        // be set to "alwaysExpired" (=0) or any value within oneShotMs
+        // allowed range.
+        //
+        // Return value:
+        //      >0: the number of transfered bytes
+        //      0:  nothing has been transfered, getLastTo() may contain an error reason
+        //
+        // Notes:
+        // - readUntilChar is copied and counted
+        // - for efficiency: Stream classes should implement peekAPI when possible
+        // - for efficiency: Stream classes should implement {input,output}TimeoutPossible()
+
+        using oneShotMs = esp8266::polledTimeout::oneShotFastMs;
+
         virtual size_t to (Print* to,
-                           const ssize_t len = -1,
-                           esp8266::polledTimeout::oneShotFastMs::timeType timeout = esp8266::polledTimeout::oneShotFastMs::neverExpires /* =>getTimeout() */,
+                           const ssize_t maxLen = -1,
+                           oneShotMs::timeType timeout = oneShotMs::neverExpires /* =>getTimeout() */,
                            int readUntilChar = -1) final;
-        enum
+        typedef enum
         {
-            TOSTREAM_SUCCESS = 0,
-            TOSTREAM_TIMED_OUT,
-            TOSTREAM_READ_ERROR,
-            TOSTREAM_WRITE_ERROR,
-            TOSTREAM_SHORT,
-        } _last_to = TOSTREAM_SUCCESS;
-
-        decltype(_last_to) getLastTo () const { return _last_to; }
+            STREAMTO_SUCCESS = 0,
+            STREAMTO_TIMED_OUT,
+            STREAMTO_READ_ERROR,
+            STREAMTO_WRITE_ERROR,
+            STREAMTO_SHORT,
+        } toReport_e;
+
+        toReport_e getLastTo () /*const*/ { return (toReport_e)getWriteError(); }
 
         //////////////////// end of extensions
 
diff --git a/cores/esp8266/StreamDev.cpp b/cores/esp8266/StreamDev.cpp
@@ -10,10 +10,10 @@ size_t Stream::to (Print* to,
                    oneShotFastMs::timeType timeout,
                    int readUntilChar)
 {
-    _last_to = TOSTREAM_SUCCESS;
+    setWriteError(STREAMTO_SUCCESS);
 
     if (len == 0)
-        return 0;   // avoid timeout for no requested data
+        return 0;   // conveniently avoids timeout for no requested data
 
     // There are two timeouts:
     // - read (network, serial, ...)
@@ -33,7 +33,7 @@ size_t Stream::to (Print* to,
     size_t written = 0;
 
     // len==-1 => maxLen=0 <=> until starvation
-    size_t maxLen = std::max((decltype(len))0, len);
+    size_t maxLen = std::max((ssize_t)0, len);
 
     if (peekBufferAPI())
 
@@ -105,7 +105,7 @@ size_t Stream::to (Print* to,
                 w = to->write(c);
                 if (w != 1)
                 {
-                    _last_to = TOSTREAM_WRITE_ERROR;
+                    setWriteError(STREAMTO_WRITE_ERROR);
                     break;
                 }
                 written += 1;
@@ -143,14 +143,14 @@ size_t Stream::to (Print* to,
                 ssize_t r = readNow(temp, w);
                 if (r < 0)
                 {
-                    _last_to = TOSTREAM_READ_ERROR;
+                    setWriteError(STREAMTO_READ_ERROR);
                     break;
                 }
                 w = to->write(temp, r);
                 written += w;
                 if ((size_t)r != w)
                 {
-                    _last_to = TOSTREAM_WRITE_ERROR;
+                    setWriteError(STREAMTO_WRITE_ERROR);
                     break;
                 }
                 if (w)
@@ -162,12 +162,18 @@ size_t Stream::to (Print* to,
                 yield();
         }
 
-    if (_last_to == TOSTREAM_SUCCESS)
+    if (getWriteError() == STREAMTO_SUCCESS)
     {
         if (timedOut)
-            _last_to = TOSTREAM_TIMED_OUT;
-        else if (len > 0 && (ssize_t)written != len)
-            _last_to = TOSTREAM_SHORT;
+            setWriteError(STREAMTO_TIMED_OUT);
+        else if ((ssize_t)written != len)
+            // This is happening when source cannot timeout (ex: a String)
+            // but has not enough data, or a dest has closed or cannot
+            // timeout but is too small (String, buffer...)
+            //
+            // Mark it as an error because user usually wants to get what is
+            // asked for.
+            setWriteError(STREAMTO_SHORT);
     }
     return written;
 }
diff --git a/libraries/ESP8266HTTPClient/src/ESP8266HTTPClient.cpp b/libraries/ESP8266HTTPClient/src/ESP8266HTTPClient.cpp
@@ -37,12 +37,12 @@ int TO2HTTPC (int streamToError)
 {
     switch (streamToError)
     {
-    case Stream::TOSTREAM_TIMED_OUT: return HTTPC_ERROR_READ_TIMEOUT;
-    case Stream::TOSTREAM_READ_ERROR: return HTTPC_ERROR_NO_STREAM;
-    case Stream::TOSTREAM_WRITE_ERROR: return HTTPC_ERROR_STREAM_WRITE;
-    case Stream::TOSTREAM_SHORT: return HTTPC_ERROR_STREAM_WRITE;
+    case Stream::STREAMTO_TIMED_OUT: return HTTPC_ERROR_READ_TIMEOUT;
+    case Stream::STREAMTO_READ_ERROR: return HTTPC_ERROR_NO_STREAM;
+    case Stream::STREAMTO_WRITE_ERROR: return HTTPC_ERROR_STREAM_WRITE;
+    case Stream::STREAMTO_SHORT: return HTTPC_ERROR_STREAM_WRITE;
     default:
-    case Stream::TOSTREAM_SUCCESS: return 0;
+    case Stream::STREAMTO_SUCCESS: return 0;
     }
 }
 
@@ -849,7 +849,7 @@ int HTTPClient::writeToStream(Stream * stream)
         ret = _client->to(stream, len);
 
         // have we an error?
-        if(_client->getLastTo() != Stream::TOSTREAM_SUCCESS) {
+        if(_client->getLastTo() != Stream::STREAMTO_SUCCESS) {
             return returnError(TO2HTTPC(ret));
         }
     } else if(_transferEncoding == HTTPC_TE_CHUNKED) {
@@ -875,7 +875,7 @@ int HTTPClient::writeToStream(Stream * stream)
             if(len > 0) {
                 // read len bytes with timeout
                 int r = _client->to(stream, len);
-                if (_client->getLastTo() != Stream::TOSTREAM_SUCCESS)
+                if (_client->getLastTo() != Stream::STREAMTO_SUCCESS)
                     // not all data transferred
                     return returnError(TO2HTTPC(ret));
                 ret += r;
