From 1fbaed9509143c394a60674db5c691a70bfc9982 Mon Sep 17 00:00:00 2001
From: Sharad Binjola <31142146+sharadb-amazon@users.noreply.github.com>
Date: Wed, 26 Jul 2023 16:48:01 -0700
Subject: [PATCH] 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 494bbc9161c00681effa8c19f02c4ea5154c3cab.

* 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 |  2 +-
 .../esp32/main/main.cpp                       |  2 +-
 src/app/server/AppDelegate.h                  | 29 +++++++++++++++++--
 src/app/server/CommissioningWindowManager.cpp |  9 +++++-
 4 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/examples/all-clusters-app/esp32/main/main.cpp b/examples/all-clusters-app/esp32/main/main.cpp
index ba16a4fddf2e49..59df30362200ef 100644
--- a/examples/all-clusters-app/esp32/main/main.cpp
+++ b/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);
diff --git a/examples/all-clusters-minimal-app/esp32/main/main.cpp b/examples/all-clusters-minimal-app/esp32/main/main.cpp
index bd447cc784e56f..ab42f2fe449668 100644
--- a/examples/all-clusters-minimal-app/esp32/main/main.cpp
+++ b/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);
diff --git a/src/app/server/AppDelegate.h b/src/app/server/AppDelegate.h
index 54c78cda0a1758..2d115d08d28f57 100644
--- a/src/app/server/AppDelegate.h
+++ b/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() {}
 };
diff --git a/src/app/server/CommissioningWindowManager.cpp b/src/app/server/CommissioningWindowManager.cpp
index a915745becbfc0..65506e1609eb3d 100644
--- a/src/app/server/CommissioningWindowManager.cpp
+++ b/src/app/server/CommissioningWindowManager.cpp
@@ -124,6 +124,8 @@ 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
@@ -131,6 +133,11 @@ void CommissioningWindowManager::HandleFailedAttempt(CHIP_ERROR err)
         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();
         }
     }
 }