Merge branch 'fix/wifi_prov_mgr_deinit_return_type_fixed' into 'master'

hrushikesh430 · hrushikesh430 · commit b9c224215e56 · 2025-07-03T08:00:10.000+08:00
fix(wifi_prov_mgr): Fixed wifi_prov_mgr_deinit api return type

Closes IDF-8204

See merge request espressif/esp-idf!39220
diff --git a/components/wifi_provisioning/include/wifi_provisioning/manager.h b/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
diff --git a/components/wifi_provisioning/src/manager.c b/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");
-        return;
+        ESP_LOGW(TAG, "Provisioning manager not initialized");
+        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,
diff --git a/docs/en/api-reference/provisioning/wifi_provisioning.rst b/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;
                 }
diff --git a/docs/en/migration-guides/release-6.x/6.0/index.rst b/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
diff --git a/docs/en/migration-guides/release-6.x/6.0/provisioning.rst b/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.
diff --git a/docs/zh_CN/api-reference/provisioning/wifi_provisioning.rst b/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() );
             }
         }
 
diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst
@@ -8,6 +8,7 @@
 
     build-system
     peripherals
+    provisioning
     security
     tools
     system
diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/provisioning.rst b/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
diff --git a/examples/network/sta2eth/main/provisioning.c b/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;
diff --git a/examples/provisioning/wifi_prov_mgr/main/app_main.c b/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 */

Original file line number	Diff line number	Diff line change
`@@ -1474,11 +1474,13 @@ void wifi_prov_mgr_wait(void)`
`1474`	`1474`	`RELEASE_LOCK(prov_ctx_lock);`
`1475`	`1475`	`}`
`1476`	`1476`
`1477`		`-void wifi_prov_mgr_deinit(void)`
	`1477`	`+esp_err_t wifi_prov_mgr_deinit(void)`
`1478`	`1478`	`{`
	`1479`	`+ esp_err_t ret = ESP_FAIL;`
	`1480`	`+`
`1479`	`1481`	`if (!prov_ctx_lock) {`
`1480`		`- ESP_LOGE(TAG, "Provisioning manager not initialized");`
`1481`		`- return;`
	`1482`	`+ ESP_LOGW(TAG, "Provisioning manager not initialized");`
	`1483`	`+ return ESP_OK;`
`1482`	`1484`	`}`
`1483`	`1485`
`1484`	`1486`	`ACQUIRE_LOCK(prov_ctx_lock);`
`@@ -1498,7 +1500,7 @@ void wifi_prov_mgr_deinit(void)`
`1498`	`1500`	`RELEASE_LOCK(prov_ctx_lock);`
`1499`	`1501`	`vSemaphoreDelete(prov_ctx_lock);`
`1500`	`1502`	`prov_ctx_lock = NULL;`
`1501`		`- return;`
	`1503`	`+ return ESP_OK;`
`1502`	`1504`	`}`
`1503`	`1505`
`1504`	`1506`	`if (prov_ctx->app_info_json) {`
`@@ -1531,8 +1533,10 @@ void wifi_prov_mgr_deinit(void)`
`1531`	`1533`	`if (app_cb) {`
`1532`	`1534`	`app_cb(app_data, WIFI_PROV_END, NULL);`
`1533`	`1535`	`}`
`1534`		`- if (esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_END, NULL, 0, portMAX_DELAY) != ESP_OK) {`
	`1536`	`+ ret = esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_END, NULL, 0, portMAX_DELAY);`
	`1537`	`+ if (ret != ESP_OK) {`
`1535`	`1538`	`ESP_LOGE(TAG, "Failed to post event WIFI_PROV_END");`
	`1539`	`+ return ret;`
`1536`	`1540`	`}`
`1537`	`1541`	`}`
`1538`	`1542`
`@@ -1545,12 +1549,15 @@ void wifi_prov_mgr_deinit(void)`
`1545`	`1549`	`if (app_cb) {`
`1546`	`1550`	`app_cb(app_data, WIFI_PROV_DEINIT, NULL);`
`1547`	`1551`	`}`
`1548`		`- if (esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_DEINIT, NULL, 0, portMAX_DELAY) != ESP_OK) {`
	`1552`	`+ ret = esp_event_post(WIFI_PROV_EVENT, WIFI_PROV_DEINIT, NULL, 0, portMAX_DELAY);`
	`1553`	`+ if (ret != ESP_OK) {`
`1549`	`1554`	`ESP_LOGE(TAG, "Failed to post event WIFI_PROV_DEINIT");`
	`1555`	`+ return ret;`
`1550`	`1556`	`}`
`1551`	`1557`
`1552`	`1558`	`vSemaphoreDelete(prov_ctx_lock);`
`1553`	`1559`	`prov_ctx_lock = NULL;`
	`1560`	`+ return ESP_OK;`
`1554`	`1561`	`}`
`1555`	`1562`
`1556`	`1563`	`esp_err_t wifi_prov_mgr_start_provisioning(wifi_prov_security_t security, const void *wifi_prov_sec_params,`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,10 @@ Wi-Fi 配网`
`78`	`78`	`break;`
`79`	`79`	`case WIFI_PROV_END:`
`80`	`80`	`/配网完成后，反初始化管理器。/`
`81`		`- wifi_prov_mgr_deinit();`
	`81`	`+ esp_err_t err = wifi_prov_mgr_deinit();`
	`82`	`+ if (err != ESP_OK) {`
	`83`	`+ ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));`
	`84`	`+ }`
`82`	`85`	`break;`
`83`	`86`	`default:`
`84`	`87`	`break;`
`@@ -172,7 +175,7 @@ Wi-Fi 配网`
`172`	`175`	`{`
`173`	`176`	`if (event_base == WIFI_PROV_EVENT && event_id == WIFI_PROV_END) {`
`174`	`177`	`/* 配网完成后反初始化管理器 */`
`175`		`- wifi_prov_mgr_deinit();`
	`178`	`+ ESP_ERROR_CHECK( wifi_prov_mgr_deinit() );`
`176`	`179`	`}`
`177`	`180`	`}`
`178`	`181`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+.. include:: ../../../../en/migration-guides/release-6.x/6.0/provisioning.rst`