Skip to content

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

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

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

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

Changes from 1 commit
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
Prev Previous commit
Next Next commit
sphinx syntax + show return values
  • Loading branch information
@mcspr
mcspr committed Oct 7, 2021
commit a04c17830ccdd2ac67bd0022b1e5ce377ebe458a
8 changes: 6 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 @@ -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.
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``, 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 <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>`
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