WiFiServer - 'rename' available() to accept() (#8419)

* WiFiServer - 'rename' available() to accept() * use server.accept() instead of available() * WiFiServer.accept() and ArduinoWiFiServer class doc update
esp8266 · Jan 3, 2022 · f401f08 · f401f08
1 parent 2f58f67
commit f401f08
Show file tree

Hide file tree

Showing 20 changed files with 53 additions and 27 deletions.
diff --git a/doc/esp8266wifi/server-class.rst b/doc/esp8266wifi/server-class.rst
@@ -12,13 +12,29 @@ Methods documented for the `Server Class <https://www.arduino.cc/en/Reference/Wi
 5. `print() <https://www.arduino.cc/en/Reference/WiFiServerPrint>`__
 6. `println() <https://www.arduino.cc/en/Reference/WiFiServerPrintln>`__
 
+In ESP8266WiFi library the ``ArduinoWiFiServer`` class implements ``available`` and the write-to-all-clients functionality as described in the Arduino WiFi library reference. The PageServer example shows how ``available`` and the write-to-all-clients works. 
+
+For most use cases the basic WiFiServer class of the ESP8266WiFi library is suitable.
+
 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.
 
+accept
+~~~~~~
+
+Method ``accept()`` returns a waiting client connection. `accept() is documented <https://www.arduino.cc/en/Reference/EthernetServerAccept>`__ for the Arduino Ethernet library.
+
+available
+~~~~~~~~~
+.. deprecated:: 3.1.0
+  see ``accept``
+
+``available`` in the ESP8266WiFi library's WiFiServer class doesn't work as documented for the Arduino WiFi library. It works the same way as ``accept``.
+
 write (write to all clients) not supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Please note that the ``write`` method on the ``WiFiServer`` object is not implemented and returns failure always.  Use the returned
-``WiFiClient`` object from the ``WiFiServer::available()`` method to communicate with individual clients.  If you need to send
+``WiFiClient`` object from the ``WiFiServer::accept()`` method to communicate with individual clients.  If you need to send
 the exact same packets to a series of clients, your application must maintain a list of connected clients and iterate over them manually.
 
 setNoDelay

diff --git a/doc/esp8266wifi/server-examples.rst b/doc/esp8266wifi/server-examples.rst
@@ -92,7 +92,7 @@ Serving of this web page will be done in the ``loop()`` where server is waiting
 
     void loop()
     {
-      WiFiClient client = server.available();
+      WiFiClient client = server.accept();
       if (client)
       {
         // we have a new client sending some request
@@ -196,7 +196,7 @@ Complete sketch is presented below.
 
     void loop()
     {
-      WiFiClient client = server.available();
+      WiFiClient client = server.accept();
       // wait for a client (web browser) to connect
       if (client)
       {

diff --git a/libraries/ESP8266AVRISP/src/ESP8266AVRISP.cpp b/libraries/ESP8266AVRISP/src/ESP8266AVRISP.cpp
@@ -72,7 +72,7 @@ AVRISPState_t ESP8266AVRISP::update() {
     switch (_state) {
         case AVRISP_STATE_IDLE: {
             if (_server.hasClient()) {
-                _client = _server.available();
+                _client = _server.accept();
                 _client.setNoDelay(true);
                 AVRISP_DEBUG("client connect %s:%d", _client.remoteIP().toString().c_str(), _client.remotePort());
                 _client.setTimeout(100); // for getch()
@@ -121,7 +121,7 @@ AVRISPState_t ESP8266AVRISP::serve() {
 }
 
 inline void ESP8266AVRISP::_reject_incoming(void) {
-    while (_server.hasClient()) _server.available().stop();
+    while (_server.hasClient()) _server.accept().stop();
 }
 
 uint8_t ESP8266AVRISP::getch() {

diff --git a/libraries/ESP8266WebServer/src/ESP8266WebServer-impl.h b/libraries/ESP8266WebServer/src/ESP8266WebServer-impl.h
@@ -281,7 +281,7 @@ void ESP8266WebServerTemplate<ServerType>::serveStatic(const char* uri, FS& fs,
 template <typename ServerType>
 void ESP8266WebServerTemplate<ServerType>::handleClient() {
   if (_currentStatus == HC_NONE) {
-    ClientType client = _server.available();
+    ClientType client = _server.accept();
     if (!client) {
       return;
     }

diff --git a/libraries/ESP8266WiFi/examples/BearSSL_Server/BearSSL_Server.ino b/libraries/ESP8266WiFi/examples/BearSSL_Server/BearSSL_Server.ino
@@ -207,7 +207,7 @@ static const char *HTTP_RES =
 
 void loop() {
   static int cnt;
-  BearSSL::WiFiClientSecure incoming = server.available();
+  BearSSL::WiFiClientSecure incoming = server.accept();
   if (!incoming) {
     return;
   }

diff --git a/libraries/ESP8266WiFi/examples/BearSSL_ServerClientCert/BearSSL_ServerClientCert.ino b/libraries/ESP8266WiFi/examples/BearSSL_ServerClientCert/BearSSL_ServerClientCert.ino
@@ -227,7 +227,7 @@ static const char *HTTP_RES =
         "</html>\r\n";
 
 void loop() {
-  BearSSL::WiFiClientSecure incoming = server.available();
+  BearSSL::WiFiClientSecure incoming = server.accept();
   if (!incoming) {
     return;
   }

diff --git a/libraries/ESP8266WiFi/examples/IPv6/IPv6.ino b/libraries/ESP8266WiFi/examples/IPv6/IPv6.ino
@@ -175,7 +175,7 @@ unsigned long statusTimeMs = 0;
 void loop() {
 
   if (statusServer.hasClient()) {
-    WiFiClient cli = statusServer.available();
+    WiFiClient cli = statusServer.accept();
     status(cli);
   }
 

diff --git a/libraries/ESP8266WiFi/examples/WiFiEcho/WiFiEcho.ino b/libraries/ESP8266WiFi/examples/WiFiEcho/WiFiEcho.ino
@@ -77,7 +77,7 @@ void loop() {
 
   //check if there are any new clients
   if (server.hasClient()) {
-    client = server.available();
+    client = server.accept();
     Serial.println("New client");
   }
 

diff --git a/libraries/ESP8266WiFi/examples/WiFiManualWebServer/WiFiManualWebServer.ino b/libraries/ESP8266WiFi/examples/WiFiManualWebServer/WiFiManualWebServer.ino
@@ -54,7 +54,7 @@ void setup() {
 
 void loop() {
   // Check if a client has connected
-  WiFiClient client = server.available();
+  WiFiClient client = server.accept();
   if (!client) {
     return;
   }

diff --git a/libraries/ESP8266WiFi/examples/WiFiTelnetToSerial/WiFiTelnetToSerial.ino b/libraries/ESP8266WiFi/examples/WiFiTelnetToSerial/WiFiTelnetToSerial.ino
@@ -130,16 +130,16 @@ void loop() {
     int i;
     for (i = 0; i < MAX_SRV_CLIENTS; i++)
       if (!serverClients[i]) { // equivalent to !serverClients[i].connected()
-        serverClients[i] = server.available();
+        serverClients[i] = server.accept();
         logger->print("New client: index ");
         logger->print(i);
         break;
       }
 
     //no free/disconnected spot so reject
     if (i == MAX_SRV_CLIENTS) {
-      server.available().println("busy");
-      // hints: server.available() is a WiFiClient with short-term scope
+      server.accept().println("busy");
+      // hints: server.accept() is a WiFiClient with short-term scope
       // when out of scope, a WiFiClient will
       // - flush() - all data will be sent
       // - stop() - automatically too

diff --git a/libraries/ESP8266WiFi/src/ArduinoWiFiServer.h b/libraries/ESP8266WiFi/src/ArduinoWiFiServer.h
@@ -35,11 +35,6 @@ class ArduinoCompatibleWiFiServerTemplate : public TServer, public Print {
   ArduinoCompatibleWiFiServerTemplate(uint16_t port) : TServer(port) {}
   virtual ~ArduinoCompatibleWiFiServerTemplate() {}
 
-  // https://www.arduino.cc/en/Reference/EthernetServerAccept
-  TClient accept() {
-    return TServer::available();
-  }
-
   // https://www.arduino.cc/en/Reference/WiFiServerAvailable
   TClient available() {
 
@@ -132,7 +127,7 @@ class ArduinoCompatibleWiFiServerTemplate : public TServer, public Print {
   void acceptClients() {
     for (uint8_t i = 0; i < MAX_MONITORED_CLIENTS; i++) {
       if (!connectedClients[i]) {
-        connectedClients[i] = accept();
+        connectedClients[i] = TServer::accept();
       }
     }
   }

diff --git a/libraries/ESP8266WiFi/src/WiFiServer.cpp b/libraries/ESP8266WiFi/src/WiFiServer.cpp
@@ -130,6 +130,10 @@ bool WiFiServer::hasMaxPendingClients() {
 
 WiFiClient WiFiServer::available(byte* status) {
     (void) status;
+    return accept();
+}
+
+WiFiClient WiFiServer::accept() {
     if (_unclaimed) {
         WiFiClient result(_unclaimed);
 

diff --git a/libraries/ESP8266WiFi/src/WiFiServer.h b/libraries/ESP8266WiFi/src/WiFiServer.h
@@ -80,7 +80,8 @@ class WiFiServer {
   WiFiServer(const IPAddress& addr, uint16_t port);
   WiFiServer(uint16_t port);
   virtual ~WiFiServer() {}
-  WiFiClient available(uint8_t* status = NULL);
+  WiFiClient accept(); // https://www.arduino.cc/en/Reference/EthernetServerAccept
+  WiFiClient available(uint8_t* status = NULL) __attribute__((deprecated("Renamed to accept().")));
   bool hasClient();
   // hasClientData():
   // returns the amount of data available from the first client

diff --git a/libraries/ESP8266WiFi/src/WiFiServerSecureBearSSL.cpp b/libraries/ESP8266WiFi/src/WiFiServerSecureBearSSL.cpp
@@ -77,6 +77,10 @@ void WiFiServerSecure::setECCert(const X509List *chain, unsigned cert_issuer_key
 // then any validation (i.e. client cert checking) will have succeeded.
 WiFiClientSecure WiFiServerSecure::available(uint8_t* status) {
   (void) status; // Unused
+  return accept();
+}
+
+WiFiClientSecure WiFiServerSecure::accept() {
   if (_unclaimed) {
     if (_sk && _sk->isRSA()) {
       WiFiClientSecure result(_unclaimed, _chain, _sk, _iobuf_in_size, _iobuf_out_size, _cache, _client_CA_ta, _tls_min, _tls_max);

diff --git a/libraries/ESP8266WiFi/src/WiFiServerSecureBearSSL.h b/libraries/ESP8266WiFi/src/WiFiServerSecureBearSSL.h
@@ -65,7 +65,8 @@ class WiFiServerSecure : public WiFiServer {
     bool setSSLVersion(uint32_t min = BR_TLS10, uint32_t max = BR_TLS12);
 
     // If awaiting connection available and authenticated (i.e. client cert), return it.
-    WiFiClientSecure available(uint8_t* status = NULL);
+    WiFiClientSecure accept(); // https://www.arduino.cc/en/Reference/EthernetServerAccept
+    WiFiClientSecure available(uint8_t* status = NULL) __attribute__((deprecated("Renamed to accept().")));
 
     WiFiServerSecure& operator=(const WiFiServerSecure&) = default;
 

diff --git a/libraries/ESP8266WiFiMesh/src/ESP8266WiFiMesh.cpp b/libraries/ESP8266WiFiMesh/src/ESP8266WiFiMesh.cpp
@@ -624,7 +624,7 @@ void ESP8266WiFiMesh::acceptRequest()
   if(_handler != NULL)
   {
     while (true) {
-      _client = _server.available();
+      _client = _server.accept();
       if (!_client)
         break;
 
@@ -647,7 +647,7 @@ void ESP8266WiFiMesh::acceptRequest()
   {
   ////////////////////////////</DEPRECATED> TODO: REMOVE IN 2.5.0////////////////////////////
     while (true) {
-      WiFiClient _client = _server.available();
+      WiFiClient _client = _server.accept();
 
       if (!_client)
         break;

diff --git a/libraries/ESP8266WiFiMesh/src/TcpIpMeshBackend.cpp b/libraries/ESP8266WiFiMesh/src/TcpIpMeshBackend.cpp
@@ -533,7 +533,7 @@ void TcpIpMeshBackend::acceptRequests()
   }
 
   while (true) {
-    WiFiClient _client = _server.available();
+    WiFiClient _client = _server.accept();
 
     if (!_client)
       break;

diff --git a/libraries/ESP8266mDNS/examples/mDNS_Web_Server/mDNS_Web_Server.ino b/libraries/ESP8266mDNS/examples/mDNS_Web_Server/mDNS_Web_Server.ino
@@ -76,7 +76,7 @@ void loop(void) {
   MDNS.update();
 
   // Check if a client has connected
-  WiFiClient client = server.available();
+  WiFiClient client = server.accept();
   if (!client) {
     return;
   }

diff --git a/libraries/Netdump/src/Netdump.cpp b/libraries/Netdump/src/Netdump.cpp
@@ -193,7 +193,7 @@ void Netdump::tcpDumpLoop(WiFiServer &tcpDumpServer, const Filter nf)
 {
     if (tcpDumpServer.hasClient())
     {
-        tcpDumpClient = tcpDumpServer.available();
+        tcpDumpClient = tcpDumpServer.accept();
         tcpDumpClient.setNoDelay(true);
 
         bufferIndex = 0;

diff --git a/tests/host/common/MockWiFiServer.cpp b/tests/host/common/MockWiFiServer.cpp
@@ -58,6 +58,11 @@ WiFiServer::WiFiServer (uint16_t port)
 WiFiClient WiFiServer::available (uint8_t* status)
 {
 	(void)status;
+	return accept();
+}
+
+WiFiClient WiFiServer::accept ()
+{
 	if (hasClient())
 		return WiFiClient(new ClientContext(serverAccept(pcb2int(_listen_pcb))));
 	return WiFiClient();