WiFiClient - rename flush() to clear() (breaking) (espressif#9453)

Co-authored-by: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com>

Author: JAndrassy

docs/en/migration_guides/2.x_to_3.0.rst

@@ -197,3 +197,11 @@ Functional changes
 * Any pin set as -1 in ``begin()`` or ``setPins()`` won't be changed nor detached.
 * ``begin(baud)`` will not change any pins that have been set before this call, through a previous ``begin(baud, rx, tx)`` or ``setPin()``.
 * If the application only uses RX or TX, ``begin(baud, -1, tx)`` or ``begin(baud, rx)`` will change only the assigned pin and keep the other unchanged.
+
+WiFi
+----
+
+Functional changes
+******************
+
+* In Arduino (and other frameworks) the method named ``flush()`` is intended to send out the transmit buffer content. ``WiFiClient`` and ``WiFiUDP`` method ``flush()`` won't clear the receive buffer anymore. A new method called ``clear()`` is now used for that. Currently ``flush()`` does nothing in ``WiFiClient``, ``WiFiClientSecure`` and ``WiFiUDP``.

libraries/Network/src/NetworkClient.cpp

@@ -159,7 +159,7 @@ class NetworkClientRxBuffer {
  return _fill - _pos + r_available();
  }
 
- void flush(){
+ void clear(){
  if(r_available()){
  fillBuffer();
  }
@@ -391,6 +391,11 @@ int NetworkClient::read()
  return data;
 }
 
+void NetworkClient::flush()
+{
+
+}
+
 size_t NetworkClient::write(const uint8_t *buf, size_t size)
 {
  int res =0;
@@ -534,11 +539,9 @@ int NetworkClient::available()
  return res;
 }
 
-// Though flushing means to send all pending data,
-// seems that in Arduino it also means to clear RX
-void NetworkClient::flush() {
+void NetworkClient::clear() {
  if (_rxBuffer != nullptr) {
- _rxBuffer->flush();
+ _rxBuffer->clear();
  }
 }
 

libraries/Network/src/NetworkClient.h

@@ -59,11 +59,12 @@ class NetworkClient : public ESPLwIPClient
  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);
+ void flush(); // Print::flush tx
  int available();
  int read();
  int read(uint8_t *buf, size_t size);
  int peek();
- void flush();
+ void clear(); // clear rx
  void stop();
  uint8_t connected();
  void setSSE(bool sse);

libraries/Network/src/NetworkUdp.cpp

@@ -288,6 +288,11 @@ size_t NetworkUDP::write(const uint8_t *buffer, size_t size){
  return i;
 }
 
+void NetworkUDP::flush()
+{
+
+}
+
 int NetworkUDP::parsePacket(){
  if(rx_buffer)
  return 0;
@@ -374,7 +379,7 @@ int NetworkUDP::peek(){
  return rx_buffer->peek();
 }
 
-void NetworkUDP::flush(){
+void NetworkUDP::clear(){
  if(!rx_buffer) return;
  cbuf *b = rx_buffer;
  rx_buffer = 0;

libraries/Network/src/NetworkUdp.h

@@ -63,13 +63,14 @@ class NetworkUDP : public UDP {
  int endPacket();
  size_t write(uint8_t);
  size_t write(const uint8_t *buffer, size_t size);
+ void flush(); // Print::flush tx
  int parsePacket();
  int available();
  int read();
  int read(unsigned char* buffer, size_t len);
  int read(char* buffer, size_t len);
  int peek();
- void flush();
+ void clear(); // clear rx
  IPAddress remoteIP();
  uint16_t remotePort();
 };

libraries/WiFi/examples/WiFiIPv6/WiFiIPv6.ino

@@ -50,7 +50,7 @@ void wifiConnectedLoop(){
  if(packetLength >= NTP_PACKET_SIZE){
  ntpClient.read(ntpPacketBuffer, NTP_PACKET_SIZE);
  }
- ntpClient.flush();
+ ntpClient.clear();
  uint32_t secsSince1900 = (uint32_t)ntpPacketBuffer[40] << 24 | (uint32_t)ntpPacketBuffer[41] << 16 | (uint32_t)ntpPacketBuffer[42] << 8 | ntpPacketBuffer[43];
  //Serial.printf("Seconds since Jan 1 1900: %u\n", secsSince1900);
  uint32_t epoch = secsSince1900 - 2208988800UL;