Darwin: Add MTRCommissioningParameters.readEndpointInformation

Endpoint information is made availalable to the delegate via an
MTRCommissioneeInfo object containing MTREndpointInfo objects.

src/darwin/Framework/CHIP/MTRAttributeTLVValueDecoder_Internal.h

@@ -1,6 +1,5 @@
-/*
- *
- *    Copyright (c) 2021 Project CHIP Authors
+/**
+ *    Copyright (c) 2021-2024 Project CHIP Authors
  *    All rights reserved.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,17 +15,21 @@
  *    limitations under the License.
  */
 
-#pragma once
-
 #import <Foundation/Foundation.h>
 
+#include <app/ClusterStateCache.h>
 #include <app/ConcreteAttributePath.h>
 #include <lib/core/CHIPError.h>
 #include <lib/core/TLV.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
+// Decodes an attribute value TLV into a typed ObjC value (see MTRStructsObjc.h)
 id _Nullable MTRDecodeAttributeValue(const chip::app::ConcreteAttributePath & aPath, chip::TLV::TLVReader & aReader,
                                      CHIP_ERROR * aError);
 
+// Wrapper around the precending function that reads the attribute from a ClusterStateCache.
+id _Nullable MTRDecodeAttributeValue(const chip::app::ConcreteAttributePath & aPath, const chip::app::ClusterStateCache & aCache,
+                                     CHIP_ERROR * aError);
+
 NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRAttributeTLVValueDecoder_Internal.mm

@@ -0,0 +1,34 @@
+/**
+ *    Copyright (c) 2024 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    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 "MTRAttributeTLVValueDecoder_Internal.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+using namespace chip;
+
+id _Nullable MTRDecodeAttributeValue(const chip::app::ConcreteAttributePath & aPath,
+    const chip::app::ClusterStateCache & aCache,
+    CHIP_ERROR * aError)
+{
+    TLV::TLVReader reader;
+    *aError = aCache.Get(aPath, reader);
+    VerifyOrReturnValue(*aError == CHIP_NO_ERROR, nil);
+    return MTRDecodeAttributeValue(aPath, reader, aError);
+}
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRCommissioningParameters.h

@@ -1,6 +1,5 @@
 /**
- *
- *    Copyright (c) 2022-2023 Project CHIP Authors
+ *    Copyright (c) 2022-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.
@@ -97,6 +96,12 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
  */
 @property (nonatomic, copy, nullable) NSString * countryCode MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
+/**
+ * Read device type information from all endpoints during commissioning.
+ * Defaults to NO.
+ */
+@property (nonatomic, assign) BOOL readEndpointInformation;
+
 @end
 
 @interface MTRCommissioningParameters (Deprecated)

src/darwin/Framework/CHIP/MTRDefines_Internal.h

@@ -1,5 +1,5 @@
 /**
- *    Copyright (c) 2023 Project CHIP Authors
+ *    Copyright (c) 2023-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.
@@ -30,8 +30,12 @@
 
 #ifdef DEBUG
 #define MTR_TESTABLE MTR_EXPORT
+#define MTR_TESTABLE_DIRECT
+#define MTR_TESTABLE_DIRECT_MEMBERS
 #else
 #define MTR_TESTABLE
+#define MTR_TESTABLE_DIRECT MTR_DIRECT
+#define MTR_TESTABLE_DIRECT_MEMBERS MTR_DIRECT_MEMBERS
 #endif
 
 // clang-format off

src/darwin/Framework/CHIP/MTRDeviceController.mm

@@ -1,6 +1,5 @@
 /**
- *
- *    Copyright (c) 2020-2023 Project CHIP Authors
+ *    Copyright (c) 2020-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.
@@ -656,11 +655,13 @@ - (void)controller:(MTRDeviceController *)controller
     } logString:__PRETTY_FUNCTION__];
 }
 
-- (void)controller:(MTRDeviceController *)controller readCommissioningInfo:(MTRProductIdentity *)info
+- (void)controller:(MTRDeviceController *)controller readCommissioneeInfo:(MTRCommissioneeInfo *)info
 {
     [self _callDelegatesWithBlock:^(id<MTRDeviceControllerDelegate> delegate) {
-        if ([delegate respondsToSelector:@selector(controller:readCommissioningInfo:)]) {
-            [delegate controller:controller readCommissioningInfo:info];
+        if ([delegate respondsToSelector:@selector(controller:readCommissioneeInfo:)]) {
+            [delegate controller:controller readCommissioneeInfo:info];
+        } else if ([delegate respondsToSelector:@selector(controller:readCommissioningInfo:)]) {
+            [delegate controller:controller readCommissioningInfo:info.productIdentity];
         }
     } logString:__PRETTY_FUNCTION__];
 }

src/darwin/Framework/CHIP/MTRDeviceControllerDelegate.h

@@ -1,6 +1,5 @@
 /**
- *
- *    Copyright (c) 2020-2023 Project CHIP Authors
+ *    Copyright (c) 2020-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.
@@ -22,6 +21,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 @class MTRDeviceController;
 @class MTRDeviceTypeRevision;
+@class MTREndpointInfo;
 @class MTRMetrics;
 @class MTRProductIdentity;
 
@@ -34,6 +34,33 @@ typedef NS_ENUM(NSInteger, MTRCommissioningStatus) {
     = 3,
 } MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
 
+/**
+ * Information read from the commissionee device during commissioning.
+ */
+MTR_NEWLY_AVAILABLE
+@interface MTRCommissioneeInfo : NSObject
+
+/**
+ * The product identity (VID / PID) of the commissionee.
+ */
+@property (nonatomic, copy, readonly) MTRProductIdentity * productIdentity;
+
+/**
+ * Endpoint information for all endpoints of the commissionee.
+ * Will be present only if readEndpointInformation is set to YES on MTRCommissioningParameters.
+ *
+ * Use `rootEndpoint` and `-[MTREndpointInfo children]` to traverse endpoints in composition order.
+ */
+@property (nonatomic, copy, readonly, nullable) NSDictionary<NSNumber *, MTREndpointInfo *> * endpointsById;
+
+/**
+ * Endpoint information for the root endpoint of the commissionee.
+ * Will be present only if readEndpointInformation is set to YES on MTRCommissioningParameters.
+ */
+@property (nonatomic, copy, readonly, nullable) MTREndpointInfo * rootEndpoint;
+
+@end
+
 /**
  * The protocol definition for the MTRDeviceControllerDelegate.
  *
@@ -87,14 +114,18 @@ MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
                   metrics:(MTRMetrics *)metrics MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
 
 /**
- * Notify the delegate when commissioning infomation has been read from the Basic
- * Information cluster of the commissionee.
+ * Notify the delegate when commissioning infomation has been read from the commissionee.
  *
- * At the point when this notification happens, device attestation has not been performed yet,
+ * Note that this notification happens before device attestation is performed,
  * so the information delivered by this notification should not be trusted.
  */
 - (void)controller:(MTRDeviceController *)controller
-    readCommissioningInfo:(MTRProductIdentity *)info MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
+    readCommissioneeInfo:(MTRCommissioneeInfo *)info MTR_NEWLY_AVAILABLE;
+
+- (void)controller:(MTRDeviceController *)controller
+    readCommissioningInfo:(MTRProductIdentity *)info
+    MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
+        MTR_NEWLY_DEPRECATED("Use controller:readCommissioneeInfo:");
 
 /**
  * Notify the delegate when the suspended state changed of the controller, after this happens

src/darwin/Framework/CHIP/MTRDeviceControllerDelegateBridge.mm

@@ -1,6 +1,5 @@
 /**
- *
- *    Copyright (c) 2020 Project CHIP Authors
+ *    Copyright (c) 2020-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.
@@ -18,6 +17,7 @@
 #import "MTRDeviceControllerDelegateBridge.h"
 #import "MTRDeviceController.h"
 #import "MTRDeviceController_Internal.h"
+#import "MTREndpointInfo_Internal.h"
 #import "MTRError_Internal.h"
 #import "MTRLogging_Internal.h"
 #import "MTRMetricKeys.h"
@@ -26,6 +26,30 @@
 
 using namespace chip::Tracing::DarwinFramework;
 
+@implementation MTRCommissioneeInfo
+
+- (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissioningInfo &)info
+{
+    self = [super init];
+    _productIdentity = [[MTRProductIdentity alloc] initWithVendorID:@(info.basic.vendorId) productID:@(info.basic.productId)];
+
+    // TODO: We should probably hold onto our MTRCommissioningParameters so we can look at `readEndpointInformation`
+    // instead of just reading whatever Descriptor cluster information happens to be in the cache.
+    auto * endpoints = [MTREndpointInfo endpointsFromAttributeCache:info.attributes];
+    if (endpoints.count > 0) {
+        _endpointsById = endpoints;
+    }
+
+    return self;
+}
+
+- (MTREndpointInfo *)rootEndpoint
+{
+    return self.endpointsById[@0];
+}
+
+@end
+
 MTRDeviceControllerDelegateBridge::MTRDeviceControllerDelegateBridge(void)
     : mDelegate(nil)
 {
@@ -125,20 +149,21 @@
 void MTRDeviceControllerDelegateBridge::OnReadCommissioningInfo(const chip::Controller::ReadCommissioningInfo & info)
 {
     MTRDeviceController * strongController = mController;
-
-    chip::VendorId vendorId = info.basic.vendorId;
-    uint16_t productId = info.basic.productId;
-
-    MTR_LOG("%@ DeviceControllerDelegate Read Commissioning Info. VendorId %u ProductId %u", strongController, vendorId, productId);
-
     id<MTRDeviceControllerDelegate> strongDelegate = mDelegate;
-    if (strongDelegate && mQueue && strongController) {
-        if ([strongDelegate respondsToSelector:@selector(controller:readCommissioningInfo:)]) {
-            dispatch_async(mQueue, ^{
-                auto * info = [[MTRProductIdentity alloc] initWithVendorID:@(vendorId) productID:@(productId)];
-                [strongDelegate controller:strongController readCommissioningInfo:info];
-            });
-        }
+    VerifyOrReturn(strongDelegate && mQueue);
+
+    // TODO: These checks are pointless since currently mController == mDelegate
+    BOOL wantCommissioneeInfo = [strongDelegate respondsToSelector:@selector(controller:readCommissioneeInfo:)];
+    BOOL wantProductIdentity = [strongDelegate respondsToSelector:@selector(controller:readCommissioningInfo:)];
+    if (wantCommissioneeInfo || wantProductIdentity) {
+        auto * commissioneeInfo = [[MTRCommissioneeInfo alloc] initWithCommissioningInfo:info];
+        dispatch_async(mQueue, ^{
+            if (wantCommissioneeInfo) { // prefer the newer delegate method over the deprecated one
+                [strongDelegate controller:strongController readCommissioneeInfo:commissioneeInfo];
+            } else if (wantProductIdentity) {
+                [strongDelegate controller:strongController readCommissioningInfo:commissioneeInfo.productIdentity];
+            }
+        });
     }
 }
 

src/darwin/Framework/CHIP/MTRDeviceController_Concrete.mm

@@ -1,6 +1,5 @@
 /**
- *
- *    Copyright (c) 2020-2023 Project CHIP Authors
+ *    Copyright (c) 2020-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.
@@ -34,6 +33,7 @@
 #import "MTRDeviceController_Concrete.h"
 #import "MTRDevice_Concrete.h"
 #import "MTRDevice_Internal.h"
+#import "MTREndpointInfo_Internal.h"
 #import "MTRError_Internal.h"
 #import "MTRKeypair.h"
 #import "MTRLogging_Internal.h"
@@ -961,6 +961,9 @@ - (BOOL)commissionNodeWithID:(NSNumber *)nodeID
 
     auto block = ^BOOL {
         chip::Controller::CommissioningParameters params;
+        if (commissioningParams.readEndpointInformation) {
+            params.SetExtraReadPaths(MTREndpointInfo.requiredAttributePaths);
+        }
         if (commissioningParams.csrNonce) {
             params.SetCSRNonce(AsByteSpan(commissioningParams.csrNonce));
         }

src/darwin/Framework/CHIP/MTREndpointInfo.h

@@ -0,0 +1,47 @@
+/**
+ *    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 <Matter/MTRDefines.h>
+
+@class MTRDeviceTypeRevision;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Meta-data about an endpoint of a Matter node.
+ */
+MTR_NEWLY_AVAILABLE
+@interface MTREndpointInfo : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@property (nonatomic, copy, readonly) NSNumber * endpointID;
+
+@property (nonatomic, copy, readonly) NSArray<MTRDeviceTypeRevision *> * deviceTypes;
+@property (nonatomic, copy, readonly) NSArray<NSNumber *> * partsList;
+
+/**
+ * The direct children of this endpoint. This excludes indirect descendants
+ * even if they are listed in the PartsList attribute of this endpoint due
+ * to the Full-Family Pattern being used. Refer to Endpoint Composition Patterns
+ * in the Matter specification for details.
+ */
+@property (nonatomic, copy, readonly) NSArray<MTREndpointInfo *> * children;
+
+@end
+
+NS_ASSUME_NONNULL_END