Merge branch 'feature/esp_netif_destroy_default_wifi' into 'master'

esp_netif/wifi: Add API to destroy default wifi-netif for sta/ap

See merge request espressif/esp-idf!12307

components/esp_netif/test/test_esp_netif.c

@@ -334,18 +334,13 @@ TEST_CASE("esp_netif: create and destroy default wifi interfaces", "[esp_netif][
     TEST_ASSERT_EQUAL(default_ap_cfg.route_prio, esp_netif_get_route_prio(ap));
 
     // destroy the station
-    esp_wifi_clear_default_wifi_driver_and_handlers(sta);
+    esp_netif_destroy_default_wifi(sta);
-    esp_netif_destroy(sta);
-
     // destroy the AP
-    esp_wifi_clear_default_wifi_driver_and_handlers(ap);
+    esp_netif_destroy_default_wifi(ap);
-    esp_netif_destroy(ap);
-
 
     // quick check on create-destroy cycle of the default station again
     sta = NULL;
     sta = esp_netif_create_default_wifi_sta();
     TEST_ASSERT_NOT_NULL(sta);
-    esp_wifi_clear_default_wifi_driver_and_handlers(sta);
+    esp_netif_destroy_default_wifi(sta);
-    esp_netif_destroy(sta);
 }

components/esp_wifi/include/esp_wifi_default.h

@@ -70,6 +70,9 @@ esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif);
 /**
  * @brief Creates default WIFI AP. In case of any init error this API aborts.
  *
+ * @note The API creates esp_netif object with default WiFi access point config,
+ * attaches the netif to wifi and registers default wifi handlers.
+ *
  * @return pointer to esp-netif instance
  */
 esp_netif_t* esp_netif_create_default_wifi_ap(void);
@@ -77,10 +80,23 @@ esp_netif_t* esp_netif_create_default_wifi_ap(void);
 /**
  * @brief Creates default WIFI STA. In case of any init error this API aborts.
  *
+ * @note The API creates esp_netif object with default WiFi station config,
+ * attaches the netif to wifi and registers default wifi handlers.
+ *
  * @return pointer to esp-netif instance
  */
 esp_netif_t* esp_netif_create_default_wifi_sta(void);
 
+/**
+ * @brief Destroys default WIFI netif created with esp_netif_create_default_wifi_...() API.
+ *
+ * @param[in] esp_netif object to detach from WiFi and destroy
+ *
+ * @note This API unregisters wifi handlers and detaches the created object from the wifi.
+ * (this function is a no-operation if esp_netif is NULL)
+ */
+void esp_netif_destroy_default_wifi(void *esp_netif);
+
 /**
  * @brief Creates esp_netif WiFi object based on the custom configuration.
  *

components/esp_wifi/src/wifi_default.c

@@ -326,6 +326,17 @@ esp_netif_t* esp_netif_create_default_wifi_sta(void)
     return netif;
 }
 
+/**
+ * @brief User init default wifi esp_netif object (official API)
+ */
+void esp_netif_destroy_default_wifi(void *esp_netif)
+{
+    if (esp_netif) {
+        esp_wifi_clear_default_wifi_driver_and_handlers(esp_netif);
+    }
+    esp_netif_destroy(esp_netif);
+}
+
 /**
  * @brief User init custom wifi interface
  */

docs/en/api-reference/network/esp_netif.rst

@@ -160,9 +160,7 @@ such as softAP and station, are provided in two separate APIs to facilitate simp
 Please note that these functions return the ``esp_netif`` handle, i.e. a pointer to a network interface object allocated and
 configured with default settings, which as a consequence, means that:
 
-* The created object has to be destroyed if a network de-initialization is provided by an application. The de-initialization should be performed in the two steps:
+* The created object has to be destroyed if a network de-initialization is provided by an application using :cpp:func:`esp_netif_destroy_default_wifi()`.
-    - :cpp:func:`esp_wifi_clear_default_wifi_driver_and_handlers()` -- To unregister default wifi handlers and detach the created object from the wifi
-    - :cpp:func:`esp_netif_destroy()` -- To destroy the ``esp_netif`` object.
 * These *default* interfaces must not be created multiple times, unless the created handle is deleted using :cpp:func:`esp_netif_destroy()`.
 * When using Wifi in ``AP+STA`` mode, both these interfaces has to be created.