diff --git a/components/esp_netif/test/test_esp_netif.c b/components/esp_netif/test/test_esp_netif.c index 4675f453bc..423c8941dc 100644 --- a/components/esp_netif/test/test_esp_netif.c +++ b/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(sta); - + esp_netif_destroy_default_wifi(sta); // destroy the AP - esp_wifi_clear_default_wifi_driver_and_handlers(ap); - esp_netif_destroy(ap); - + esp_netif_destroy_default_wifi(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(sta); + esp_netif_destroy_default_wifi(sta); } diff --git a/components/esp_wifi/include/esp_wifi_default.h b/components/esp_wifi/include/esp_wifi_default.h index 4ce7f8b28e..958977bf25 100644 --- a/components/esp_wifi/include/esp_wifi_default.h +++ b/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. * diff --git a/components/esp_wifi/src/wifi_default.c b/components/esp_wifi/src/wifi_default.c index bc494857c4..bd15054150 100644 --- a/components/esp_wifi/src/wifi_default.c +++ b/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 */ diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst index 81d534f82a..d04d481c85 100644 --- a/docs/en/api-reference/network/esp_netif.rst +++ b/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: - - :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. +* 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()`. * 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.