Merge branch 'fix/esp_netif_remove_deprecated_api' into 'master'

[esp_netif]: Remove deprecated APIs

Closes IDF-10213

See merge request espressif/esp-idf!42125

components/esp_netif/esp_netif_objects.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -71,13 +71,6 @@ size_t esp_netif_get_nr_of_ifs(void)
     return s_esp_netif_counter;
 }
 
-// This API is inherently unsafe
-// suggest that users call from esp_netif_tcpip_exec()
-esp_netif_t* esp_netif_next(esp_netif_t* netif)
-{
-    return esp_netif_next_unsafe(netif);
-}
-
 esp_netif_t* esp_netif_next_unsafe(esp_netif_t* netif)
 {
     ESP_LOGV(TAG, "%s %p", __func__, netif);

components/esp_netif/include/esp_netif.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -981,25 +981,6 @@ int esp_netif_set_route_prio(esp_netif_t *esp_netif, int route_prio);
 int32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type);
 
 
-/**
- * @brief Iterates over list of interfaces. Returns first netif if NULL given as parameter
- *
- * @note This API doesn't lock the list, nor the TCPIP context, as this it's usually required
- * to get atomic access between iteration steps rather that within a single iteration.
- * Therefore it is recommended to iterate over the interfaces inside esp_netif_tcpip_exec()
- *
- * @note This API is deprecated. Please use esp_netif_next_unsafe() directly if all the system
- * interfaces are under your control and you can safely iterate over them.
- * Otherwise, iterate over interfaces using esp_netif_tcpip_exec(), or use esp_netif_find_if()
- * to search in the list of netifs with defined predicate.
- *
- * @param[in]  esp_netif Handle to esp-netif instance
- *
- * @return First netif from the list if supplied parameter is NULL, next one otherwise
- */
-esp_netif_t *esp_netif_next(esp_netif_t *esp_netif)
-__attribute__((deprecated("use esp_netif_next_unsafe() either directly or via esp_netif_tcpip_exec")));
-
 /**
  * @brief Iterates over list of interfaces without list locking. Returns first netif if NULL given as parameter
  *

docs/en/migration-guides/release-6.x/6.0/networking.rst

@@ -42,3 +42,69 @@ Removed the following RMII clock Kconfig options from `components/esp_eth`. Cloc
 
 **Impact**: Applications using ``ETH_ESP32_EMAC_DEFAULT_CONFIG()`` continue to work. Custom clock configurations must be set explicitly in the EMAC config structure or use the `Ethernet Init component <https://components.espressif.com/components/espressif/ethernet_init>`_.
 
+
+ESP-NETIF
+*********
+
+Removal of deprecated :cpp:func:`esp_netif_next`
+------------------------------------------------
+
+The deprecated iteration helper :cpp:func:`esp_netif_next` has been removed from :doc:`/api-reference/network/esp_netif`. This API was inherently unsafe because it did not lock the interface list or the TCP/IP context during iteration.
+
+Use one of the following alternatives:
+
+- Directly call :cpp:func:`esp_netif_next_unsafe` only in contexts you fully control, or inside :cpp:func:`esp_netif_tcpip_exec` for safe execution within the TCP/IP context.
+- Use :cpp:func:`esp_netif_find_if` with a predicate to search for specific interfaces without manual iteration.
+
+Migration
+~~~~~~~~~
+
+Before:
+
+.. code-block:: c
+
+    esp_netif_t *it = NULL;
+    while ((it = esp_netif_next(it)) != NULL) {
+        // use "it"
+    }
+
+After (iterate unsafely in a controlled context):
+
+.. code-block:: c
+
+    esp_netif_t *it = NULL;
+    while ((it = esp_netif_next_unsafe(it)) != NULL) {
+        // use "it"
+    }
+
+Recommended (iterate within TCP/IP context):
+
+.. code-block:: c
+
+    static esp_err_t iterate_netifs(void *ctx)
+    {
+        esp_netif_t *it = NULL;
+        while ((it = esp_netif_next_unsafe(it)) != NULL) {
+            // use "it"
+        }
+        return ESP_OK;
+    }
+
+    // Execute iteration safely in TCP/IP context
+    ESP_ERROR_CHECK(esp_netif_tcpip_exec(iterate_netifs, NULL));
+
+Alternative (find with predicate):
+
+.. code-block:: c
+
+    static bool match_by_key(void *ctx, esp_netif_t *netif)
+    {
+        const char *wanted = (const char *)ctx;
+        const char *key = esp_netif_get_ifkey(netif);
+        return key && strcmp(key, wanted) == 0;
+    }
+
+    esp_netif_t *target = esp_netif_find_if(match_by_key, (void *)"WIFI_STA_DEF");
+    if (target) {
+        // use "target"
+    }

docs/zh_CN/migration-guides/release-6.x/6.0/networking.rst

@@ -42,3 +42,69 @@
 
 **影响**：使用 ``ETH_ESP32_EMAC_DEFAULT_CONFIG()`` 的应用程序可继续正常工作。自定义时钟配置需在 EMAC 配置结构体中显式设置，或使用 `Ethernet Init 组件 <https://components.espressif.com/components/espressif/ethernet_init>`_。
 
+
+ESP-NETIF
+*********
+
+移除弃用的 :cpp:func:`esp_netif_next`
+-------------------------------------
+
+已从 :doc:`/api-reference/network/esp_netif` 中移除弃用的迭代辅助函数 :cpp:func:`esp_netif_next`。该 API 在迭代过程中不会对接口列表或 TCP/IP 上下文进行加锁，因而并不安全。
+
+请使用以下替代方案：
+
+- 仅在完全可控的上下文中直接调用 :cpp:func:`esp_netif_next_unsafe`，或在 :cpp:func:`esp_netif_tcpip_exec` 中执行以保证在 TCP/IP 上下文内安全运行。
+- 使用 :cpp:func:`esp_netif_find_if` 并配合谓词查找特定接口，从而避免手动迭代。
+
+迁移方式
+~~~~~~~~~
+
+之前：
+
+.. code-block:: c
+
+    esp_netif_t *it = NULL;
+    while ((it = esp_netif_next(it)) != NULL) {
+        // 使用 "it"
+    }
+
+之后（在可控上下文中进行不加锁迭代）：
+
+.. code-block:: c
+
+    esp_netif_t *it = NULL;
+    while ((it = esp_netif_next_unsafe(it)) != NULL) {
+        // 使用 "it"
+    }
+
+推荐方式（在 TCP/IP 上下文中迭代）：
+
+.. code-block:: c
+
+    static esp_err_t iterate_netifs(void *ctx)
+    {
+        esp_netif_t *it = NULL;
+        while ((it = esp_netif_next_unsafe(it)) != NULL) {
+            // 使用 "it"
+        }
+        return ESP_OK;
+    }
+
+    // 在 TCP/IP 上下文中安全执行迭代
+    ESP_ERROR_CHECK(esp_netif_tcpip_exec(iterate_netifs, NULL));
+
+替代方式（使用谓词查找）：
+
+.. code-block:: c
+
+    static bool match_by_key(void *ctx, esp_netif_t *netif)
+    {
+        const char *wanted = (const char *)ctx;
+        const char *key = esp_netif_get_ifkey(netif);
+        return key && strcmp(key, wanted) == 0;
+    }
+
+    esp_netif_t *target = esp_netif_find_if(match_by_key, (void *)"WIFI_STA_DEF");
+    if (target) {
+        // 使用 "target"
+    }