Addressed comments by sharadb-amazon

Author: pgregorr-amazon

examples/tv-casting-app/android/App/app/src/main/jni/com/matter/casting/support/ConnectionCallbacks.java

@@ -13,23 +13,40 @@
  */
 package com.matter.casting.support;
 
-/** @brief A container struct for User Directed Commissioning (UDC) callbacks. */
+/** @brief A container class for User Directed Commissioning (UDC) callbacks. */
 public class ConnectionCallbacks {
 
-  /** (Required) The callback called when the connection is established successfully. */
+  /** The callback called when the connection is established successfully. */
   public final MatterCallback<Void> onSuccess;
 
-  /** (Required) The callback called with MatterError when the connection is fails to establish. */
+  /** The callback called with MatterError when the connection is fails to establish. */
   public final MatterCallback<MatterError> onFailure;
 
   /**
-   * (Optional) The callback called when the Client/Commissionee receives a CommissionerDeclaration
-   * message from the CastingPlayer/Commissioner. This callback is needed to support UDC features
-   * where a reply from the Commissioner is expected. It provides information indicating the
-   * Commissioner’s pre-commissioning state.
+   * The callback called when the Client/Commissionee receives a CommissionerDeclaration message
+   * from the CastingPlayer/Commissioner. This callback is needed to support UDC features where a
+   * reply from the Commissioner is expected. It provides information indicating the Commissioner’s
+   * pre-commissioning state.
    */
   public MatterCallback<CommissionerDeclaration> onCommissionerDeclaration;
 
+  /**
+   * The constructor for ConnectionCallbacks, the container class for User Directed Commissioning
+   * (UDC) callbacks.
+   *
+   * @param onSuccess (Required) The callback called when the connection is established
+   *     successfully.
+   * @param onFailure (Required) The callback called with MatterError when the connection is fails
+   *     to establish.
+   * @param onCommissionerDeclaration (Optional) The callback called when the Client/Commissionee
+   *     receives a CommissionerDeclaration message from the CastingPlayer/Commissioner. This
+   *     callback is needed to support UDC features where a reply from the Commissioner is expected.
+   *     It provides information indicating the Commissioner’s pre-commissioning state.
+   *     <p>For example: During CastingPlayer/Commissioner-Generated passcode commissioning, the
+   *     Commissioner replies with a CommissionerDeclaration message with PasscodeDialogDisplayed
+   *     and CommissionerPasscode set to true. Given these Commissioner state details, the client is
+   *     expected to perform some actions and responf accrdingly.
+   */
   public ConnectionCallbacks(
       MatterCallback<Void> onSuccess,
       MatterCallback<MatterError> onFailure,

examples/tv-casting-app/android/App/app/src/main/jni/com/matter/casting/support/IdentificationDeclarationOptions.java

@@ -19,8 +19,8 @@
 
 /**
  * This class contains the optional parameters used in the IdentificationDeclaration Message, sent
- * by the Commissionee to the Commissioner. The options specify information relating to the
- * requested UDC commissioning session.
+ * by the Commissionee (CastingApp) to the Commissioner (CastingPlayer). The options specify
+ * information relating to the requested UDC commissioning session.
  */
 public class IdentificationDeclarationOptions {
   private final String TAG = IdentificationDeclarationOptions.class.getSimpleName();

examples/tv-casting-app/android/App/app/src/main/jni/cpp/core/MatterCastingPlayer-JNI.h

@@ -50,7 +50,14 @@ class MatterCastingPlayerJNI
 private:
     friend MatterCastingPlayerJNI & MatterCastingPlayerJNIMgr();
     static MatterCastingPlayerJNI sInstance;
+
+    // Handles the connection complete event and calls the ConnectionCallbacks onSuccess or onFailure callback provided by the Java
+    // client. This callback is called by the cpp layer when the connection process has ended, regardless of whether it was
+    // successful or not.
     static void ConnectCallback(CHIP_ERROR err, CastingPlayer * playerPtr);
+    // Handles the Commissioner Declaration event and calls the ConnectionCallbacks onCommissionerDeclaration callback provided by
+    // the Java client. This callback is called by the cpp layer when the Commissionee receives a CommissionerDeclaration message
+    // from the CastingPlayer/Commissioner.
     static void CommissionerDeclarationCallback(const chip::Transport::PeerAddress & source,
                                                 chip::Protocols::UserDirectedCommissioning::CommissionerDeclaration cd);
 };

examples/tv-casting-app/darwin/MatterTvCastingBridge/MatterTvCastingBridge.xcodeproj/project.pbxproj

@@ -12,6 +12,7 @@
 		39589F162B91556B00BE040C /* MCInteractionModelStructs.h in Headers */ = {isa = PBXBuildFile; fileRef = 39589F152B91556B00BE040C /* MCInteractionModelStructs.h */; };
 		39589F182B91557700BE040C /* MCInteractionModelStructs.mm in Sources */ = {isa = PBXBuildFile; fileRef = 39589F172B91557700BE040C /* MCInteractionModelStructs.mm */; };
 		395BF6AF2C18EC7C00C73CE2 /* MCTargetAppInfo.mm in Sources */ = {isa = PBXBuildFile; fileRef = 395BF6AE2C18EC7C00C73CE2 /* MCTargetAppInfo.mm */; };
+		397099D92C2255FE00B34428 /* MCCastingApp_Internal.h in Headers */ = {isa = PBXBuildFile; fileRef = 397099D82C2255FE00B34428 /* MCCastingApp_Internal.h */; };
 		399BCE1E2C13CBAD0075AA85 /* MCTargetAppInfo.h in Headers */ = {isa = PBXBuildFile; fileRef = 399BCE1D2C13CBAD0075AA85 /* MCTargetAppInfo.h */; };
 		39BF57C52B8CFF790081653C /* MCAttributeObjects.h in Headers */ = {isa = PBXBuildFile; fileRef = 39BF57C42B8CFF790081653C /* MCAttributeObjects.h */; };
 		39BF57C72B8CFFB90081653C /* MCAttributeObjects.mm in Sources */ = {isa = PBXBuildFile; fileRef = 39BF57C62B8CFFB90081653C /* MCAttributeObjects.mm */; };
@@ -96,6 +97,7 @@
 		39589F152B91556B00BE040C /* MCInteractionModelStructs.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MCInteractionModelStructs.h; sourceTree = "<group>"; };
 		39589F172B91557700BE040C /* MCInteractionModelStructs.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = MCInteractionModelStructs.mm; sourceTree = "<group>"; };
 		395BF6AE2C18EC7C00C73CE2 /* MCTargetAppInfo.mm */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.objcpp; path = MCTargetAppInfo.mm; sourceTree = "<group>"; };
+		397099D82C2255FE00B34428 /* MCCastingApp_Internal.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MCCastingApp_Internal.h; sourceTree = "<group>"; };
 		399049A62B9FC4ED000C91F0 /* MCCommandPayloads_Internal.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MCCommandPayloads_Internal.h; sourceTree = "<group>"; };
 		399BCE1D2C13CBAD0075AA85 /* MCTargetAppInfo.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MCTargetAppInfo.h; sourceTree = "<group>"; };
 		39BF57C42B8CFF790081653C /* MCAttributeObjects.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MCAttributeObjects.h; sourceTree = "<group>"; };
@@ -275,6 +277,7 @@
 				395241F42B854EA700F7DB91 /* zap-generated */,
 				3CCB87202869085400771BAD /* MatterTvCastingBridge.h */,
 				3CF71C092A992D0D003A5CE5 /* MCCastingApp.h */,
+				397099D82C2255FE00B34428 /* MCCastingApp_Internal.h */,
 				3CF71C0B2A992D25003A5CE5 /* MCCastingApp.mm */,
 				3C2346222B362B9500FA276E /* MCCastingPlayerDiscovery.h */,
 				3C2346242B362BBB00FA276E /* MCCastingPlayerDiscovery.mm */,
@@ -347,6 +350,7 @@
 				39BF57CD2B8FC0EF0081653C /* MCClusterObjects.h in Headers */,
 				39D4D2502B97942D00BF3CFE /* MCCommandObjects.h in Headers */,
 				3C621CA52B605A6A005CDBA3 /* MCAttribute.h in Headers */,
+				397099D92C2255FE00B34428 /* MCCastingApp_Internal.h in Headers */,
 				3CD73F1C2A9E8396009D82D1 /* MCCommissionableDataProvider.h in Headers */,
 				3C4F521E2B4F4B3B00BB8A10 /* MCEndpoint_Internal.h in Headers */,
 				39BF57C92B8D66540081653C /* NSStringSpanConversion.h in Headers */,

examples/tv-casting-app/darwin/MatterTvCastingBridge/MatterTvCastingBridge/MCCastingApp.h

@@ -42,16 +42,6 @@
  */
 - (NSError * _Nullable)initializeWithDataSource:(id<MCDataSource> _Nonnull)dataSource;
 
-/**
- * @brief Updates the MCCommissionableDataProvider stored in this CastingApp with the new CommissionableData
- * to be used for the next commissioning session. Calling this function is mandatory for the
- * Casting Player/Commissioner-Generated passcode commissioning flow, since the commissioning session's PAKE
- * verifier needs to be updated with the user entered passcode.
- *
- * @param newCommissionableData the new MCCommissionableData to be used for the next commissioning session.
- */
-- (NSError * _Nullable)updateCommissionableDataProvider:(MCCommissionableData * _Nonnull)newCommissionableData;
-
 /**
  * @brief (async) Starts the Matter server that the MCCastingApp runs on and registers all the necessary delegates
  */

examples/tv-casting-app/darwin/MatterTvCastingBridge/MatterTvCastingBridge/MCCastingApp.mm

@@ -15,7 +15,7 @@
  *    limitations under the License.
  */
 
-#import "MCCastingApp.h"
+#import "MCCastingApp_Internal.h"
 
 #import "MCCommissionableDataProvider.h"
 #import "MCCommonCaseDeviceServerInitParamsProvider.h"
@@ -43,8 +43,7 @@ @interface MCCastingApp ()
 // queue used to perform all work performed by the MatterTvCastingBridge
 @property (atomic) dispatch_queue_t workQueue;
 
-// used to update the commissionableDataProvider post initialization, this is necessary for the
-// Commissioner-Generated passcode commissioning feature.
+// Client defiend data source used to initialize the MCCommissionableDataProvider and, if needed, update the MCCommissionableDataProvider post initialization. This is necessary for the Commissioner-Generated passcode commissioning feature.
 @property (nonatomic, strong) id<MCDataSource> dataSource;
 
 @end
@@ -74,6 +73,7 @@ - (dispatch_queue_t)getClientQueue
 - (NSError *)initializeWithDataSource:(id)dataSource
 {
     ChipLogProgress(AppServer, "MCCastingApp.initializeWithDataSource() called");
+    // store the data source provided by the client
     _dataSource = dataSource;
 
     // get the clientQueue
@@ -109,14 +109,10 @@ - (NSError *)initializeWithDataSource:(id)dataSource
     return [MCErrorUtils NSErrorFromChipError:CHIP_NO_ERROR];
 }
 
-- (NSError *)updateCommissionableDataProvider:(MCCommissionableData *)newCommissionableData
+- (NSError *)updateCommissionableDataProvider
 {
     ChipLogProgress(AppServer, "MCCastingApp.UpdateCommissionableDataProvider() called");
 
-    if (_dataSource) {
-        [_dataSource update:newCommissionableData];
-    }
-
     _commissionableDataProvider = new matter::casting::support::MCCommissionableDataProvider();
     VerifyOrReturnValue(_commissionableDataProvider->Initialize(_dataSource) == CHIP_NO_ERROR,
         [MCErrorUtils NSErrorFromChipError:CHIP_ERROR_INVALID_ARGUMENT]);

examples/tv-casting-app/darwin/MatterTvCastingBridge/MatterTvCastingBridge/MCCastingApp_Internal.h

@@ -0,0 +1,37 @@
+/**
+ *
+ *    Copyright (c) 2024 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import "MCCastingApp.h"
+
+#import <Foundation/Foundation.h>
+
+#ifndef MCCastingApp_Internal_h
+#define MCCastingApp_Internal_h
+
+@interface MCCastingApp ()
+
+/**
+ * @brief (Private internal method) Updates the MCCommissionableDataProvider stored in this CastingApp with the updated CommissionableData
+ * to be used for the next commissioning session. Calling this function is mandatory for the
+ * Casting Player/Commissioner-Generated passcode commissioning flow, since the commissioning session's PAKE
+ * verifier needs to be updated with the user entered passcode.
+ */
+- (NSError *)updateCommissionableDataProvider;
+
+@end
+
+#endif /*  MCCastingApp_Internal_h */

examples/tv-casting-app/darwin/MatterTvCastingBridge/MatterTvCastingBridge/MCCastingPlayer.h

@@ -50,7 +50,7 @@
  *     expected to perform some actions, detailed in the continueConnecting() API below, and then
  *     call the continueConnecting() API to complete the process.
  * @param timeout time (in sec) to keep the commissioning window open, if commissioning is required.
- *     Needs to be >= CastingPlayer.kMinCommissioningWindowTimeoutSec.
+ *     Needs to be >= MCCastingPlayer.kMinCommissioningWindowTimeoutSec.
  * @param identificationDeclarationOptions (Optional) Parameters in the IdentificationDeclaration
  *     message sent by the Commissionee to the Commissioner. These parameters specify the
  *     information relating to the requested commissioning session.
@@ -60,26 +60,45 @@
  *     list of optional parameters.
  *     <p>Furthermore, attributes (such as VendorId) describe the TargetApp/Endpoint that the client
  *     wants to interact with after commissioning. If this value is passed in,
- *    verifyOrEstablishConnection() will force UDC, in case the desired TargetApp is not found in
+ *     verifyOrEstablishConnection() will force UDC, in case the desired TargetApp is not found in
  *     the on-device cached information/CastingStore.
  * @return nil if request submitted successfully, otherwise a NSError object corresponding to the error.
  */
-- (NSError *)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks
-                                              timeout:(long)timeout
-                     identificationDeclarationOptions:(MCIdentificationDeclarationOptions * _Nullable)identificationDeclarationOptions;
+- (NSError * _Nullable)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks
+                                                        timeout:(long)timeout
+                               identificationDeclarationOptions:(MCIdentificationDeclarationOptions * _Nullable)identificationDeclarationOptions;
 
 /**
- * @brief The simplified version of the verifyOrEstablishConnectionWithCallbacks() API above.
+ * @brief Verifies that a connection exists with this CastingPlayer, or triggers a new
+ *     commissioning session request. If the CastingApp does not have the nodeId and fabricIndex
+ *     of this CastingPlayer cached on disk, this will execute the User Directed Commissioning
+ *     (UDC) process by sending an IdentificationDeclaration message to the Commissioner. This method will run verifyOrEstablishConnection() with a default timeout of MCCastingPlayer.kMinCommissioningWindowTimeoutSec.
+ * @param identificationDeclarationOptions (Optional) Parameters in the IdentificationDeclaration
+ *     message sent by the Commissionee to the Commissioner. These parameters specify the
+ *     information relating to the requested commissioning session.
+ *     <p>For example: To invoke the CastingPlayer/Commissioner-Generated passcode commissioning
+ *     flow, the client would call this API with IdentificationDeclarationOptions containing
+ *     CommissionerPasscode set to true. See IdentificationDeclarationOptions.java for a complete
+ *     list of optional parameters.
+ *     <p>Furthermore, attributes (such as VendorId) describe the TargetApp/Endpoint that the client
+ *     wants to interact with after commissioning. If this value is passed in,
+ *     verifyOrEstablishConnection() will force UDC, in case the desired TargetApp is not found in
+ *     the on-device cached information/CastingStore.
  * @return nil if request submitted successfully, otherwise a NSError object corresponding to the error.
+ * @see verifyOrEstablishConnectionWithCallbacks:timeout:identificationDeclarationOptions:
  */
-- (NSError *)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks
-                     identificationDeclarationOptions:(MCIdentificationDeclarationOptions * _Nullable)identificationDeclarationOptions;
+- (NSError * _Nullable)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks
+                               identificationDeclarationOptions:(MCIdentificationDeclarationOptions * _Nullable)identificationDeclarationOptions;
 
 /**
- * @brief The simplified version of the verifyOrEstablishConnectionWithCallbacks() API above.
+ * @brief Verifies that a connection exists with this CastingPlayer, or triggers a new
+ *     commissioning session request. If the CastingApp does not have the nodeId and fabricIndex
+ *     of this CastingPlayer cached on disk, this will execute the User Directed Commissioning
+ *     (UDC) process by sending an IdentificationDeclaration message to the Commissioner. This method will run verifyOrEstablishConnection() with a default timeout of MCCastingPlayer.kMinCommissioningWindowTimeoutSec and MCIdentificationDeclarationOptions initailized with the defualt values.
  * @return nil if request submitted successfully, otherwise a NSError object corresponding to the error.
+ * @see verifyOrEstablishConnectionWithCallbacks:timeout:identificationDeclarationOptions:
  */
-- (NSError *)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks;
+- (NSError * _Nullable)verifyOrEstablishConnectionWithCallbacks:(MCConnectionCallbacks * _Nonnull)connectionCallbacks;
 
 /**
  * @brief This is a continuation of the CastingPlayer/Commissioner-Generated passcode
@@ -97,13 +116,13 @@
  *     <p>5. Client prompted user to input Passcode from Commissioner.
  *     <p>6. Client has updated the CastingApp's MCCommissionableDataProvider with the user entered
  *     passcode via the following function call:
- *     MCCastingApp.updateCommissionableDataProvider(MCCommissionableData). This updates the
+ *     MCDataSource.update(MCCommissionableData). This updates the
  *     commissioning session's PAKE verifier with the user entered passcode.
  *     <p>Note: The same connectionCallbacks and commissioningWindowTimeoutSec parameters passed
  *     into verifyOrEstablishConnection() will be used.
  * @return nil if request submitted successfully, otherwise a NSError object corresponding to the error.
  */
-- (NSError *)continueConnecting;
+- (NSError * _Nullable)continueConnecting;
 
 /**
  * @brief This cancels the CastingPlayer/Commissioner-Generated passcode commissioning flow
@@ -117,7 +136,7 @@
  *     VerifyOrEstablishConnection() API above since no connection is established.
  * @return nil if request submitted successfully, otherwise a NSError object corresponding to the error.
  */
-- (NSError *)stopConnecting;
+- (NSError * _Nullable)stopConnecting;
 
 /**
  * @brief Sets the internal connection state of this MCCastingPlayer to "disconnected"