Improves WiFiMulti (#9139)

* feat(wifi): Improves WiFiMulti

* fix(wifi): Fixes Initialization of Security Mode

* feat(wifi): simplifies the example by using HTTPClient

* fix(WiFi): fixes a type in the commentaries

libraries/WiFi/examples/WiFiMultiAdvanced/WiFiMultiAdvanced.ino

+/*
+ *  This sketch tries to connect to the best AP available
+ *  and tests for captive portals on open networks
+ *
+ */
+
+#include <WiFi.h>
+#include <WiFiMulti.h>
+#include <HTTPClient.h>
+
+WiFiMulti wifiMulti;
+
+// callback used to check Internet connectivity
+bool testConnection(){
+  HTTPClient http;
+  http.begin("http://www.espressif.com");
+  int httpCode = http.GET();
+  // we expect to get a 301 because it will ask to use HTTPS instead of HTTP
+  if (httpCode == HTTP_CODE_MOVED_PERMANENTLY) return true;
+  return false;
+}
+
+void setup()
+{
+    Serial.begin(115200);
+    delay(10);
+
+    wifiMulti.addAP("ssid_from_AP_1", "your_password_for_AP_1");
+    wifiMulti.addAP("ssid_from_AP_2", "your_password_for_AP_2");
+    wifiMulti.addAP("ssid_from_AP_3", "your_password_for_AP_3");
+
+    // These options can help when you need ANY kind of wifi connection to get a config file, report errors, etc.
+    wifiMulti.setStrictMode(false);  // Default is true.  Library will disconnect and forget currently connected AP if it's not in the AP list.
+    wifiMulti.setAllowOpenAP(true);   // Default is false.  True adds open APs to the AP list.
+    wifiMulti.setConnectionTestCallbackFunc(testConnection);   // Attempts to connect to a remote webserver in case of captive portals.
+
+    Serial.println("Connecting Wifi...");
+    if(wifiMulti.run() == WL_CONNECTED) {
+        Serial.println("");
+        Serial.println("WiFi connected");
+        Serial.println("IP address: ");
+        Serial.println(WiFi.localIP());
+    }
+}
+
+void loop()
+{
+    static bool isConnected = false; 
+    uint8_t WiFiStatus = wifiMulti.run();
+    
+    if (WiFiStatus == WL_CONNECTED) {
+        if (!isConnected) {
+            Serial.println("");
+            Serial.println("WiFi connected");
+            Serial.println("IP address: ");
+            Serial.println(WiFi.localIP());
+        }
+        isConnected = true;
+    } else {
+        Serial.println("WiFi not connected!");
+        isConnected = false; 
+        delay(5000);
+    }
+}

libraries/WiFi/src/WiFiMulti.h

@@ -32,8 +32,11 @@
 typedef struct {
     char * ssid;
     char * passphrase;
+    bool hasFailed;
 } WifiAPlist_t;
 
+typedef std::function<bool(void)> ConnectionTestCB_t;
+
 class WiFiMulti
 {
 public:
@@ -41,13 +44,36 @@ public:
     ~WiFiMulti();
 
     bool addAP(const char* ssid, const char *passphrase = NULL);
-
-    void enableIPv6(bool state);
     uint8_t run(uint32_t connectTimeout=5000);
+    void enableIPv6(bool state);
+
+    // Force (default: true) to only keep connected or to connect to an AP from the provided WiFiMulti list.
+    // When bStrict is false, it will keep the last/current connected AP even if not in the WiFiMulti List.
+    void setStrictMode(bool bStrict = true);
+    
+    // allows (true) to connect to ANY open AP, even if not in the user list
+    // default false (do not connect to an open AP that has not been explicitaly added by the user to list)
+    void setAllowOpenAP(bool bAllowOpenAP = false);
+
+    // clears the current list of Multi APs and frees the memory
+    void APlistClean(void);
+
+    // allow the user to define a callback function that will validate the connection to the Internet.
+    // if the callback returns true, the connection is considered valid and the AP will added to the validated AP list.
+    // set the callback to NULL to disable the feature and validate any SSID that is in the list.
+    void setConnectionTestCallbackFunc(ConnectionTestCB_t cbFunc);
 
 private:
     std::vector<WifiAPlist_t> APlist;
     bool ipv6_support;
+
+    bool _bStrict = true;
+    bool _bAllowOpenAP = false;
+    ConnectionTestCB_t _connectionTestCBFunc = NULL;
+    bool _bWFMInit = false;
+
+    void markAsFailed(int32_t i);
+    void resetFails();
 };
 
 #endif /* WIFICLIENTMULTI_H_ */