Darwin: Add MTRCommissioningParameters.readEndpointInformation (project-chip#37118)

* Darwin: Tidy up some device type meta-data classes

- Move MTRDeviceTypeRevision out of ServerEndpoint directory
- Move MTRProductIdentity into its own file
- Implement NSCopying and equality on MTRDeviceType and MTRProductIdentity
- Implement description on all 3 types
- Add tests

* Darwin: Add MTRCommissioningParameters.readEndpointInformation

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

* Apply suggestions from code review

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

* Use NSString literal for MTRDeviceTypeData

* Process endpoints in best-effort fashion even with invalid / missing DeviceTypeList

Also add some additional comments to parsing logic and a couple more tests.

* Address further review comments for Darwin layer

* Move MTRCommissioneeInfo into its own set of files

* Make MTRCommissioneeInfo and related types conform to NSSecureCoding

Also conform to NSCopying, mark as sendable, and implement isEqual/hash.

* Fix terminology a bit.

---------

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

Author: ksperling-apple

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/MTRCommissioneeInfo.h

@@ -0,0 +1,52 @@
+/**
+ *    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 MTRProductIdentity;
+@class MTREndpointInfo;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Information read from the commissionee device during commissioning.
+ */
+NS_SWIFT_SENDABLE
+MTR_NEWLY_AVAILABLE
+@interface MTRCommissioneeInfo : NSObject <NSCopying, NSSecureCoding>
+
+/**
+ * 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
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRCommissioneeInfo.mm

@@ -0,0 +1,95 @@
+/**
+ *    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 "MTRCommissioneeInfo_Internal.h"
+
+#import "MTRDefines_Internal.h"
+#import "MTREndpointInfo_Internal.h"
+#import "MTRProductIdentity.h"
+#import "MTRUtilities.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+MTR_DIRECT_MEMBERS
+@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;
+}
+
+static NSString * const sProductIdentityCodingKey = @"pi";
+static NSString * const sEndpointsCodingKey = @"ep";
+
+- (nullable instancetype)initWithCoder:(NSCoder *)coder
+{
+    self = [super init];
+    _productIdentity = [coder decodeObjectOfClass:MTRProductIdentity.class forKey:sProductIdentityCodingKey];
+    VerifyOrReturnValue(_productIdentity != nil, nil);
+    _endpointsById = [coder decodeDictionaryWithKeysOfClass:NSNumber.class
+                                             objectsOfClass:MTREndpointInfo.class
+                                                     forKey:sEndpointsCodingKey];
+    return self;
+}
+
+- (void)encodeWithCoder:(NSCoder *)coder
+{
+    [coder encodeObject:_productIdentity forKey:sProductIdentityCodingKey];
+    [coder encodeObject:_endpointsById forKey:sEndpointsCodingKey];
+}
+
++ (BOOL)supportsSecureCoding
+{
+    return YES;
+}
+
+- (NSUInteger)hash
+{
+    return _productIdentity.hash;
+}
+
+- (BOOL)isEqual:(id)object
+{
+    VerifyOrReturnValue([object class] == [self class], NO);
+    MTRCommissioneeInfo * other = object;
+    VerifyOrReturnValue(MTREqualObjects(_productIdentity, other->_productIdentity), NO);
+    VerifyOrReturnValue(MTREqualObjects(_endpointsById, other->_endpointsById), NO);
+    return YES;
+}
+
+- (id)copyWithZone:(nullable NSZone *)zone
+{
+    return self; // immutable
+}
+
+- (nullable MTREndpointInfo *)rootEndpoint
+{
+    return self.endpointsById[@0];
+}
+
+@end
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRCommissioneeInfo_Internal.h

@@ -0,0 +1,32 @@
+/**
+ *    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/MTRCommissioneeInfo.h>
+
+#import "MTRDefines_Internal.h"
+
+#include <controller/CommissioningDelegate.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+MTR_DIRECT_MEMBERS
+@interface MTRCommissioneeInfo ()
+
+- (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissioningInfo &)info;
+
+@end
+
+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 MTR_NEWLY_AVAILABLE;
+
 @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.
@@ -20,6 +19,13 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+@class MTRCommissioneeInfo;
+@class MTRDeviceController;
+@class MTRDeviceTypeRevision;
+@class MTREndpointInfo;
+@class MTRMetrics;
+@class MTRProductIdentity;
+
 typedef NS_ENUM(NSInteger, MTRCommissioningStatus) {
     MTRCommissioningStatusUnknown = 0,
     MTRCommissioningStatusSuccess = 1,
@@ -29,22 +35,6 @@ typedef NS_ENUM(NSInteger, MTRCommissioningStatus) {
     = 3,
 } MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
 
-/**
- * A representation of a (vendor, product) pair that identifies a specific product.
- */
-MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
-@interface MTRProductIdentity : NSObject
-
-@property (nonatomic, copy, readonly) NSNumber * vendorID;
-
-@property (nonatomic, copy, readonly) NSNumber * productID;
-
-- (instancetype)initWithVendorID:(NSNumber *)vendorID productID:(NSNumber *)productID;
-@end
-
-@class MTRDeviceController;
-@class MTRMetrics;
-
 /**
  * The protocol definition for the MTRDeviceControllerDelegate.
  *
@@ -98,14 +88,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