AppDelegate updates: new callback and docs (#28240)

* Adding OnCommissioningSessionEstablishmentError(err) to AppDelegate * Removed error param from OnCommissioningSessionStopped and added docs for all of AppDelegate * Addressing feedback from tcarmelveilleux@ * Revert "Addressing feedback from tcarmelveilleux@" This reverts commit 494bbc9. * Addressing feedback from bzbarsky-apple@ * Update src/app/server/AppDelegate.h Co-authored-by: Boris Zbarsky <[email protected]> * Restyled --------- Co-authored-by: Boris Zbarsky <[email protected]>
project-chip · Aug 22, 2023 · 4915561 · 4915561
1 parent a37b185
commit 4915561
Show file tree

Hide file tree

Showing 5 changed files with 37 additions and 7 deletions.
diff --git a/examples/all-clusters-app/esp32/main/main.cpp b/examples/all-clusters-app/esp32/main/main.cpp
@@ -87,7 +87,7 @@ class AppCallbacks : public AppDelegate
 public:
     void OnCommissioningSessionEstablishmentStarted() {}
     void OnCommissioningSessionStarted() override { bluetoothLED.Set(true); }
-    void OnCommissioningSessionStopped(CHIP_ERROR err) override
+    void OnCommissioningSessionStopped() override
     {
         bluetoothLED.Set(false);
         pairingWindowLED.Set(false);

diff --git a/examples/all-clusters-minimal-app/esp32/main/main.cpp b/examples/all-clusters-minimal-app/esp32/main/main.cpp
@@ -86,7 +86,7 @@ class AppCallbacks : public AppDelegate
 public:
     void OnCommissioningSessionEstablishmentStarted() {}
     void OnCommissioningSessionStarted() override { bluetoothLED.Set(true); }
-    void OnCommissioningSessionStopped(CHIP_ERROR err) override
+    void OnCommissioningSessionStopped() override
     {
         bluetoothLED.Set(false);
         pairingWindowLED.Set(false);

diff --git a/examples/platform/telink/common/src/AppTaskCommon.cpp b/examples/platform/telink/common/src/AppTaskCommon.cpp
@@ -140,7 +140,7 @@ class AppCallbacks : public AppDelegate
 public:
     void OnCommissioningSessionEstablishmentStarted() {}
     void OnCommissioningSessionStarted() override { isComissioningStarted = true; }
-    void OnCommissioningSessionStopped(CHIP_ERROR err) override { isComissioningStarted = false; }
+    void OnCommissioningSessionStopped() override { isComissioningStarted = false; }
     void OnCommissioningWindowClosed() override
     {
         if (!isComissioningStarted)

diff --git a/src/app/server/AppDelegate.h b/src/app/server/AppDelegate.h
@@ -29,20 +29,43 @@ class AppDelegate
 public:
     virtual ~AppDelegate() {}
     /**
-     * This is called on start of session establishment process
+     * This is called when the PBKDFParamRequest is received and indicates the start of the session establishment process
      */
     virtual void OnCommissioningSessionEstablishmentStarted() {}
+
+    /**
+     * This is called when the commissioning session has been established
+     */
     virtual void OnCommissioningSessionStarted() {}
-    virtual void OnCommissioningSessionStopped(CHIP_ERROR err) {}
+
+    /**
+     * This is called when the PASE establishment failed (such as, when an invalid passcode is provided) or PASE was established
+     * fine but then the fail-safe expired (including being expired by the commissioner)
+     *
+     * @param err CHIP_ERROR indicating the error that occurred during session establishment or the error accompanying the fail-safe
+     * timeout.
+     */
+    virtual void OnCommissioningSessionEstablishmentError(CHIP_ERROR err) {}
+
+    /**
+     * This is called when the PASE establishment failed or PASE was established fine but then the fail-safe expired (including
+     * being expired by the commissioner) AND the commissioning window is closed. The window may be closed because the commissioning
+     * attempts limit was reached or advertising/listening for PASE failed.
+     */
+    virtual void OnCommissioningSessionStopped() {}
 
     /*
-     * This is called anytime a basic or enhanced commissioning window is opened.
+     * This is called any time a basic or enhanced commissioning window is opened.
      *
      * The type of the window can be retrieved by calling
      * CommissioningWindowManager::CommissioningWindowStatusForCluster(), but
      * being careful about how to handle the None status when a window is in
      * fact open.
      */
     virtual void OnCommissioningWindowOpened() {}
+
+    /*
+     * This is called any time a basic or enhanced commissioning window is closed.
+     */
     virtual void OnCommissioningWindowClosed() {}
 };
diff --git a/src/app/server/CommissioningWindowManager.cpp b/src/app/server/CommissioningWindowManager.cpp
@@ -152,13 +152,20 @@ void CommissioningWindowManager::HandleFailedAttempt(CHIP_ERROR err)
 #if CONFIG_NETWORK_LAYER_BLE
     mServer->GetBleLayerObject()->CloseAllBleConnections();
 #endif
+
+    CHIP_ERROR prevErr = err;
     if (mFailedCommissioningAttempts < kMaxFailedCommissioningAttempts)
     {
         // If the number of commissioning attempts has not exceeded maximum
         // retries, let's start listening for commissioning connections again.
         err = AdvertiseAndListenForPASE();
     }
 
+    if (mAppDelegate != nullptr)
+    {
+        mAppDelegate->OnCommissioningSessionEstablishmentError(prevErr);
+    }
+
     if (err != CHIP_NO_ERROR)
     {
         // The commissioning attempts limit was exceeded, or listening for
@@ -167,7 +174,7 @@ void CommissioningWindowManager::HandleFailedAttempt(CHIP_ERROR err)
 
         if (mAppDelegate != nullptr)
         {
-            mAppDelegate->OnCommissioningSessionStopped(err);
+            mAppDelegate->OnCommissioningSessionStopped();
         }
     }
 }