From 9deef3571eebadf46a05c02fe9b034ac9e14e059 Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Tue, 5 Oct 2021 01:17:16 +0300 Subject: [PATCH 1/3] documentation: add description for connected() and status() ref. the original PR and the discussion https://github.com/esp8266/Arduino/pull/4626 https://github.com/esp8266/Arduino/issues/6701 --- doc/esp8266wifi/client-class.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/esp8266wifi/client-class.rst b/doc/esp8266wifi/client-class.rst index 11e412181e..b0e30af2eb 100644 --- a/doc/esp8266wifi/client-class.rst +++ b/doc/esp8266wifi/client-class.rst @@ -16,7 +16,17 @@ Methods documented for `Client `__ 10. `stop() `__ -Methods and properties described further down are specific to ESP8266. They are not covered in `Arduino WiFi library `__ documentation. Before they are fully documented please refer to information below. +Methods and properties described further down below are specific to ESP8266. Some of them behave differently from the reference `Arduino WiFi library `__ , or are only implemented for this Core. + +connected +~~~~~~~~~ + +Unlike the reference implementation, ``connected()`` means that the client is available for both reads and writes. Please use ``status()`` for only the connection information, and ``available()`` if you mean to check whether there's unread data. + +status +~~~~~~ + +Current implementation returns ``0`` (``CLOSED``) when the client is disconnected and ``4`` (``ESTABLISHED``) when connected. At the time of writing these refer to the ``enum tcp_state`` values that can be found at the `lwip/tcpbase.h ` flush and stop ~~~~~~~~~~~~~~ @@ -92,7 +102,6 @@ Other Function Calls .. code:: cpp - uint8_t status () virtual size_t write (const uint8_t *buf, size_t size) size_t write_P (PGM_P buf, size_t size) size_t write (Stream &stream) From a04c17830ccdd2ac67bd0022b1e5ce377ebe458a Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Thu, 7 Oct 2021 15:57:32 +0300 Subject: [PATCH 2/3] sphinx syntax + show return values --- doc/esp8266wifi/client-class.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/esp8266wifi/client-class.rst b/doc/esp8266wifi/client-class.rst index b0e30af2eb..01545156de 100644 --- a/doc/esp8266wifi/client-class.rst +++ b/doc/esp8266wifi/client-class.rst @@ -21,12 +21,16 @@ Methods and properties described further down below are specific to ESP8266. Som connected ~~~~~~~~~ -Unlike the reference implementation, ``connected()`` means that the client is available for both reads and writes. Please use ``status()`` for only the connection information, and ``available()`` if you mean to check whether there's unread data. +Unlike the reference implementation, ``connected()`` means that the client is available for both reads and writes. It will return ``true`` when the client is ``status() == ESTABLISHED`` or ``available() == true``, but will return ``false`` when the ``status() == CLOSED``. Please use ``status()`` for the connection information, ``availableForWrite()`` to check whether it is possible to write, and ``available()`` if you mean to check whether there's unread data. + +When the remote side closes the connection e.g. we receive a fairly small payload through HTTP with ``Connection: close``, it is possible to have ``connected() == false`` while the ``available() > 0``. Attempting to ``write()`` to such connection will not be possible, so it is expected from the sketch to also check for ``availableForWrite() > 0`` first. + +This change was introduced with `#4626 `__, part of the Core release `2.4.2 `__ status ~~~~~~ -Current implementation returns ``0`` (``CLOSED``) when the client is disconnected and ``4`` (``ESTABLISHED``) when connected. At the time of writing these refer to the ``enum tcp_state`` values that can be found at the `lwip/tcpbase.h ` +Current implementation returns ``0`` / ``CLOSED`` when the client is disconnected and ``4`` / ``ESTABLISHED`` when connected. At the time of writing these refer to the ``enum tcp_state`` values that can be found at the `lwip/tcpbase.h `__ flush and stop ~~~~~~~~~~~~~~ From f887fd9e57d3ba4b9df9d6b634fcd138c5090609 Mon Sep 17 00:00:00 2001 From: Maxim Prokhorov Date: Thu, 7 Oct 2021 15:59:04 +0300 Subject: [PATCH 3/3] words --- doc/esp8266wifi/client-class.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/esp8266wifi/client-class.rst b/doc/esp8266wifi/client-class.rst index 01545156de..be216e9910 100644 --- a/doc/esp8266wifi/client-class.rst +++ b/doc/esp8266wifi/client-class.rst @@ -23,7 +23,7 @@ connected Unlike the reference implementation, ``connected()`` means that the client is available for both reads and writes. It will return ``true`` when the client is ``status() == ESTABLISHED`` or ``available() == true``, but will return ``false`` when the ``status() == CLOSED``. Please use ``status()`` for the connection information, ``availableForWrite()`` to check whether it is possible to write, and ``available()`` if you mean to check whether there's unread data. -When the remote side closes the connection e.g. we receive a fairly small payload through HTTP with ``Connection: close``, it is possible to have ``connected() == false`` while the ``available() > 0``. Attempting to ``write()`` to such connection will not be possible, so it is expected from the sketch to also check for ``availableForWrite() > 0`` first. +When the remote side closes the connection e.g. we receive a fairly small payload through HTTP with ``Connection: close``, client will return ``connected() == false`` while the ``available() > 0``. Attempting to ``write()`` to such connection will not be possible, so it is expected from the sketch to check first for the ``availableForWrite() > 0``. This change was introduced with `#4626 `__, part of the Core release `2.4.2 `__