AppDelegate updates: new callback and docs (project-chip#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 <bzbarsky@apple.com>

* Restyled

---------

Co-authored-by: Boris Zbarsky <bzbarsky@apple.com>

examples/all-clusters-app/esp32/main/main.cpp

@@ -83,7 +83,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);

examples/all-clusters-minimal-app/esp32/main/main.cpp

@@ -84,7 +84,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);

src/app/server/AppDelegate.h

@@ -29,18 +29,41 @@ 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::CommissioningWindowStatus()
      */
     virtual void OnCommissioningWindowOpened() {}
+
+    /*
+     * This is called any time a basic or enhanced commissioning window is closed.
+     */
     virtual void OnCommissioningWindowClosed() {}
 };

src/app/server/CommissioningWindowManager.cpp

@@ -124,13 +124,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
@@ -139,7 +146,7 @@ void CommissioningWindowManager::HandleFailedAttempt(CHIP_ERROR err)
 
         if (mAppDelegate != nullptr)
         {
-            mAppDelegate->OnCommissioningSessionStopped(err);
+            mAppDelegate->OnCommissioningSessionStopped();
         }
     }
 }