Merge branch 'fix/wifi_prov_mgr_deinit_return_type_fixed' into 'master'

fix(wifi_prov_mgr): Fixed wifi_prov_mgr_deinit api return type

Closes IDF-8204

See merge request espressif/esp-idf!39220

components/wifi_provisioning/include/wifi_provisioning/manager.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
  */
@@ -280,8 +280,13 @@ esp_err_t wifi_prov_mgr_init(wifi_prov_mgr_config_t config);
  * If provisioning service is  still active when this API is called,
  * it first stops the service, hence emitting WIFI_PROV_END, and
  * then performs the de-initialization
+ *
+ * @return
+ *  - ESP_OK         : Success
+ *  - ESP_FAIL       : Failed to post event WIFI_PROV_DEINIT or WIFI_PROV_END
+ *  - ESP_ERR_NO_MEM : Out of memory (as may be returned by esp_event_post)
  */
-void wifi_prov_mgr_deinit(void);
+esp_err_t wifi_prov_mgr_deinit(void);
 
 /**
  * @brief   Checks if device is provisioned

components/wifi_provisioning/src/manager.c

@@ -1474,11 +1474,13 @@ void wifi_prov_mgr_wait(void)
     RELEASE_LOCK(prov_ctx_lock);
 }
 
-void wifi_prov_mgr_deinit(void)
+esp_err_t wifi_prov_mgr_deinit(void)
 {
+    esp_err_t ret = ESP_FAIL;
+
     if (!prov_ctx_lock) {
-        ESP_LOGE(TAG, "Provisioning manager not initialized");
+        ESP_LOGW(TAG, "Provisioning manager not initialized");
-        return;
+        return ESP_OK;
     }
 
     ACQUIRE_LOCK(prov_ctx_lock);
@@ -1498,7 +1500,7 @@ void wifi_prov_mgr_deinit(void)
         RELEASE_LOCK(prov_ctx_lock);
         vSemaphoreDelete(prov_ctx_lock);
         prov_ctx_lock = NULL;
-        return;
+        return ESP_OK;
     }
 
     if (prov_ctx->app_info_json) {
@@ -1531,8 +1533,10 @@ void wifi_prov_mgr_deinit(void)
         if (app_cb) {
             app_cb(app_data, WIFI_PROV_END, NULL);
         }
-        if (esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_END, NULL, 0, portMAX_DELAY) != ESP_OK) {
+        ret = esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_END, NULL, 0, portMAX_DELAY);
+        if (ret != ESP_OK) {
             ESP_LOGE(TAG, "Failed to post event WIFI_PROV_END");
+            return ret;
         }
     }
 
@@ -1545,12 +1549,15 @@ void wifi_prov_mgr_deinit(void)
     if (app_cb) {
         app_cb(app_data, WIFI_PROV_DEINIT, NULL);
     }
-    if (esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_DEINIT, NULL, 0, portMAX_DELAY) != ESP_OK) {
+    ret = esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_DEINIT, NULL, 0, portMAX_DELAY);
+    if (ret != ESP_OK) {
         ESP_LOGE(TAG, "Failed to post event WIFI_PROV_DEINIT");
+        return ret;
     }
 
     vSemaphoreDelete(prov_ctx_lock);
     prov_ctx_lock = NULL;
+    return ESP_OK;
 }
 
 esp_err_t wifi_prov_mgr_start_provisioning(wifi_prov_security_t security, const void *wifi_prov_sec_params,

docs/en/api-reference/provisioning/wifi_provisioning.rst

@@ -76,10 +76,14 @@ The configuration structure :cpp:type:`wifi_prov_mgr_config_t` has a few fields
                     case WIFI_PROV_CRED_SUCCESS:
                         ESP_LOGI(TAG, "Provisioning successful");
                         break;
-                    case WIFI_PROV_END:
+                    case WIFI_PROV_END: {
                         /* De-initialize manager once provisioning is finished */
-                        wifi_prov_mgr_deinit();
+                        esp_err_t err = wifi_prov_mgr_deinit();
+                        if (err != ESP_OK) {
+                            ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));
+                        }
                         break;
+                    }
                     default:
                         break;
                 }

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

@@ -8,6 +8,7 @@ Migration from 5.5 to 6.0
 
     build-system
     peripherals
+    provisioning
     security
     tools
     system

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

@@ -0,0 +1,9 @@
+Provisioning
+==================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Breaking Changes
+----------------
+
+The return type of :cpp:func:`wifi_prov_mgr_deinit` has been changed from ``void`` to :cpp:type:`esp_err_t`. This change allows applications to properly handle potential failures during provisioning manager deinitialization.

docs/zh_CN/api-reference/provisioning/wifi_provisioning.rst

@@ -78,7 +78,10 @@ Wi-Fi 配网
                         break;
                     case WIFI_PROV_END:
                         /*配网完成后，反初始化管理器。*/
-                        wifi_prov_mgr_deinit();
+                        esp_err_t err = wifi_prov_mgr_deinit();
+                        if (err != ESP_OK) {
+                            ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));
+                        }
                         break;
                     default:
                         break;
@@ -172,7 +175,7 @@ Wi-Fi 配网
         {
             if (event_base == WIFI_PROV_EVENT && event_id == WIFI_PROV_END) {
                 /* 配网完成后反初始化管理器 */
-                wifi_prov_mgr_deinit();
+                ESP_ERROR_CHECK( wifi_prov_mgr_deinit() );
             }
         }
 

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

@@ -8,6 +8,7 @@
 
     build-system
     peripherals
+    provisioning
     security
     tools
     system

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

@@ -0,0 +1 @@
+.. include:: ../../../../en/migration-guides/release-6.x/6.0/provisioning.rst

examples/network/sta2eth/main/provisioning.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Unlicense OR CC0-1.0
  */
@@ -120,7 +120,10 @@ static void event_handler(void *arg, esp_event_base_t event_base,
         break;
     case WIFI_PROV_END:
         /* De-initialize manager once provisioning is finished */
-        wifi_prov_mgr_deinit();
+        esp_err_t err = wifi_prov_mgr_deinit();
+        if (err != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));
+        }
         xEventGroupSetBits(*handler_args->flags, handler_args->success ? handler_args->success_bit : handler_args->fail_bit);
         free(handler_args);
         break;

examples/provisioning/wifi_prov_mgr/main/app_main.c

@@ -147,7 +147,10 @@ static void event_handler(void* arg, esp_event_base_t event_base,
                 break;
             case WIFI_PROV_END:
                 /* De-initialize manager once provisioning is finished */
-                wifi_prov_mgr_deinit();
+                esp_err_t err = wifi_prov_mgr_deinit();
+                if (err != ESP_OK) {
+                    ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));
+                }
                 break;
             default:
                 break;
@@ -520,7 +523,7 @@ void app_main(void)
 
         /* We don't need the manager as device is already provisioned,
          * so let's release it's resources */
-        wifi_prov_mgr_deinit();
+        ESP_ERROR_CHECK(wifi_prov_mgr_deinit());
 
         ESP_ERROR_CHECK(esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &event_handler, NULL));
         /* Start Wi-Fi station */