Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

documentation: add description for connected() and status() #8329

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

documentation: add description for connected() and status() #8329

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9deef35
documentation: add description for connected() and status()
mcspr Oct 4, 2021
a04c178
sphinx syntax + show return values
mcspr Oct 7, 2021
f887fd9
words
mcspr Oct 7, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions doc/esp8266wifi/client-class.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,21 @@ Methods documented for `Client <https://www.arduino.cc/en/Reference/WiFiClientCo
9. `flush() <https://www.arduino.cc/en/Reference/WiFiClientFlush>`__
10. `stop() <https://www.arduino.cc/en/Reference/WiFIClientStop>`__

Methods and properties described further down are specific to ESP8266. They are not covered in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ 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 <https://www.arduino.cc/en/Reference/WiFi>`__ , or are only implemented for this Core.

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.
Copy link
Collaborator

@d-a-v d-a-v Jan 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will return true when the client is status() == ESTABLISHED or available() == true, but will return false when the status() == CLOSED.

According to current code, it will return false if the connection is closed, regardless available() result,
meaning "writing is not allowed".

available() can still be checked to tell if something has been received but kept unread.

Arduino/libraries/ESP8266WiFi/src/WiFiClient.cpp

Lines 329 to 335 in f401f08

uint8_t WiFiClient::connected()
{
if (!_client || _client->state() == CLOSED)
return 0;
return _client->state() == ESTABLISHED || available();
}


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 <https://github.com/esp8266/Arduino/pull/4626>`__, part of the Core release `2.4.2 <https://github.com/esp8266/Arduino/releases/tag/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 <https://github.com/esp8266/Arduino/blob/master/tools/sdk/lwip2/include/lwip/tcpbase.h>`__

flush and stop
~~~~~~~~~~~~~~
Expand Down Expand Up @@ -92,7 +106,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)
Expand Down