Expose Network Commissioning FeatureMap values on MTRCommissioneeInfo. (#40778)

bzbarsky-apple · web-flow · commit 04dd945c3e5f · 2025-09-28T22:22:36.000Z
* Expose Network Commissioning FeatureMap values on MTRCommissioneeInfo.

This is easier for API consumers than dealing with the "attributes" data
structures.

* Address review comments.

* Address more review comments.
diff --git a/src/darwin/Framework/CHIP/MTRCommissioneeInfo.h b/src/darwin/Framework/CHIP/MTRCommissioneeInfo.h
@@ -19,6 +19,7 @@
 
 @class MTRProductIdentity;
 @class MTREndpointInfo;
+@class MTRNetworkInterfaceInfo;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -57,6 +58,12 @@ MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4))
  */
 @property (nonatomic, copy, readonly, nullable) NSDictionary<MTRAttributePath *, NSDictionary<NSString *, id> *> * attributes MTR_AVAILABLE(ios(26.2), macos(26.2), watchos(26.2), tvos(26.2));
 
+/**
+ * Network interfaces the commissionee has.  The array will be empty if there
+ * are no network interfaces exposed on the commissionee.
+ */
+@property (nonatomic, copy, readonly) NSArray<MTRNetworkInterfaceInfo *> * networkInterfaces MTR_UNSTABLE_API;
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/src/darwin/Framework/CHIP/MTRCommissioneeInfo.mm b/src/darwin/Framework/CHIP/MTRCommissioneeInfo.mm
@@ -24,6 +24,7 @@
 #import "MTRDeviceDataValidation.h"
 #import "MTREndpointInfo_Internal.h"
 #import "MTRLogging_Internal.h"
+#import "MTRNetworkInterfaceInfo_Internal.h"
 #import "MTRProductIdentity.h"
 #import "MTRUtilities.h"
 
@@ -37,6 +38,8 @@ @implementation MTRCommissioneeInfo
 
 - (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissioningInfo &)info commissioningParameters:(MTRCommissioningParameters *)commissioningParameters
 {
+    using namespace chip::app;
+
     self = [super init];
     _productIdentity = [[MTRProductIdentity alloc] initWithVendorID:@(info.basic.vendorId) productID:@(info.basic.productId)];
 
@@ -47,13 +50,15 @@ - (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissio
         }
     }
 
+    NSMutableArray<MTRNetworkInterfaceInfo *> * networkInterfaces = [[NSMutableArray alloc] init];
+
     if (info.attributes != nullptr) {
         NSMutableDictionary<MTRAttributePath *, NSDictionary<NSString *, id> *> * attributes = [[NSMutableDictionary alloc] init];
 
         // Only expose attributes that match pathFilters, so that API consumers
         // don't start relying on undocumented internal details of which paths
         // we read from the device in which circumstances.
-        std::vector<chip::app::AttributePathParams> pathFilters;
+        std::vector<AttributePathParams> pathFilters;
         if (commissioningParameters.extraAttributesToRead != nil) {
             for (MTRAttributeRequestPath * requestPath in commissioningParameters.extraAttributesToRead) {
                 [requestPath convertToAttributePathParams:pathFilters.emplace_back()];
@@ -64,7 +69,7 @@ - (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissio
         // attributes, using a wildcard-endpoint path.
         pathFilters.emplace_back(MTRClusterIDTypeNetworkCommissioningID, MTRAttributeIDTypeGlobalAttributeFeatureMapID);
 
-        info.attributes->ForEachAttribute([&](const chip::app::ConcreteAttributePath & path) -> CHIP_ERROR {
+        info.attributes->ForEachAttribute([&](const ConcreteAttributePath & path) -> CHIP_ERROR {
             // Only grab paths that are included in extraAttributesToRead so that
             // API consumers don't develop dependencies on implementation details
             // (like which other attributes we happen to read).
@@ -111,14 +116,42 @@ - (instancetype)initWithCommissioningInfo:(const chip::Controller::ReadCommissio
         });
 
         _attributes = attributes;
+
+        // Now grab the Network Commissioning information in a nicer form.
+        info.attributes->ForEachAttribute(MTRClusterIDTypeNetworkCommissioningID, [&](const ConcreteAttributePath & path) -> CHIP_ERROR {
+            if (path.mAttributeId != MTRAttributeIDTypeGlobalAttributeFeatureMapID) {
+                return CHIP_NO_ERROR;
+            }
+
+            uint32_t value;
+            CHIP_ERROR err = info.attributes->Get<Clusters::NetworkCommissioning::Attributes::FeatureMap::TypeInfo>(path, value);
+            if (err != CHIP_NO_ERROR) {
+                // Keep iterating no matter what.
+                return CHIP_NO_ERROR;
+            }
+
+            MTRNetworkInterfaceInfo * _Nullable interfaceInfo = [[MTRNetworkInterfaceInfo alloc] initWithEndpointID:@(path.mEndpointId) featureMap:@(value)];
+            if (!interfaceInfo) {
+                // Invalid feature map.  Just keep looking for other ones.
+                return CHIP_NO_ERROR;
+            }
+
+            [networkInterfaces addObject:interfaceInfo];
+            return CHIP_NO_ERROR;
+        });
     }
 
+    auto * endpointDescriptor = [[NSSortDescriptor alloc] initWithKey:@"endpointID" ascending:YES];
+    [networkInterfaces sortUsingDescriptors:@[ endpointDescriptor ]];
+    _networkInterfaces = networkInterfaces;
+
     return self;
 }
 
 static NSString * const sProductIdentityCodingKey = @"pi";
 static NSString * const sEndpointsCodingKey = @"ep";
 static NSString * const sAttributesCodingKey = @"at";
+static NSString * const sNetworkInterfacesCodingKey = @"ni";
 
 - (nullable instancetype)initWithCoder:(NSCoder *)coder
 {
@@ -156,6 +189,15 @@ - (nullable instancetype)initWithCoder:(NSCoder *)coder
         }
     }
 
+    // Decode network interface array (may be nil if decoding something encoded
+    // before we added these properties).
+    _networkInterfaces = [coder decodeArrayOfObjectsOfClass:MTRNetworkInterfaceInfo.class forKey:sNetworkInterfacesCodingKey];
+
+    // Provide empty array for backward compatibility if not present in encoded data
+    if (_networkInterfaces == nil) {
+        _networkInterfaces = @[];
+    }
+
     return self;
 }
 
@@ -164,6 +206,7 @@ - (void)encodeWithCoder:(NSCoder *)coder
     [coder encodeObject:_productIdentity forKey:sProductIdentityCodingKey];
     [coder encodeObject:_endpointsById forKey:sEndpointsCodingKey];
     [coder encodeObject:_attributes forKey:sAttributesCodingKey];
+    [coder encodeObject:_networkInterfaces forKey:sNetworkInterfacesCodingKey];
 }
 
 + (BOOL)supportsSecureCoding
@@ -183,6 +226,7 @@ - (BOOL)isEqual:(id)object
     VerifyOrReturnValue(MTREqualObjects(_productIdentity, other->_productIdentity), NO);
     VerifyOrReturnValue(MTREqualObjects(_endpointsById, other->_endpointsById), NO);
     VerifyOrReturnValue(MTREqualObjects(_attributes, other->_attributes), NO);
+    VerifyOrReturnValue(MTREqualObjects(_networkInterfaces, other->_networkInterfaces), NO);
 
     return YES;
 }
diff --git a/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo.h b/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo.h
@@ -0,0 +1,54 @@
+/**
+ *    Copyright (c) 2025 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 <Foundation/Foundation.h>
+#import <Matter/MTRBaseClusters.h>
+#import <Matter/MTRDefines.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Information about a network interface on a Matter node.
+ */
+
+NS_SWIFT_SENDABLE
+MTR_UNSTABLE_API
+@interface MTRNetworkInterfaceInfo : NSObject <NSCopying, NSSecureCoding>
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/**
+ * The endpoint this network interface is exposed on (i.e. the endpoint its
+ * corresponding Network Commissioning server cluster instance is on).
+ */
+@property (nonatomic, copy, readonly) NSNumber * endpointID;
+
+/**
+ * The value of the FeatureMap attribute of the corresponding Network
+ * Commissioning cluster instance.
+ */
+@property (nonatomic, copy, readonly) NSNumber * featureMap;
+
+/**
+ * The network technology used by the interface.  This will be one of the
+ * MTRNetworkCommissioningFeature*NetworkInterface values (exactly one bit).
+ */
+@property (nonatomic, assign, readonly) MTRNetworkCommissioningFeature type;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo.mm b/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo.mm
@@ -0,0 +1,120 @@
+/**
+ *    Copyright (c) 2025 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 "MTRNetworkInterfaceInfo_Internal.h"
+
+#import <Matter/MTRBaseClusters.h>
+
+#import "MTRDefines_Internal.h"
+#import "MTRLogging_Internal.h"
+#import "MTRUtilities.h"
+
+#include <lib/support/CodeUtils.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+MTR_DIRECT_MEMBERS
+@implementation MTRNetworkInterfaceInfo
+
+- (nullable instancetype)initWithEndpointID:(NSNumber *)endpointID featureMap:(NSNumber *)featureMap
+{
+    constexpr MTRNetworkCommissioningFeature typeBits = (MTRNetworkCommissioningFeatureWiFiNetworkInterface | MTRNetworkCommissioningFeatureThreadNetworkInterface | MTRNetworkCommissioningFeatureEthernetNetworkInterface);
+    auto ourTypeBits = featureMap.unsignedLongLongValue & typeBits;
+
+    if (ourTypeBits == 0) {
+        MTR_LOG_ERROR("MTRNetworkInterfaceInfo for endpoint %@ has no network technology bits set", endpointID);
+        return nil;
+    }
+
+    if ((ourTypeBits & (ourTypeBits - 1)) != 0) {
+        MTR_LOG_ERROR("MTRNetworkInterfaceInfo for endpoint %@ has multiple network technology bits set: 0x%llx", endpointID, ourTypeBits);
+        return nil;
+    }
+
+    if (!(self = [super init])) {
+        return nil;
+    }
+
+    _endpointID = [endpointID copy];
+    _featureMap = [featureMap copy];
+    _type = static_cast<MTRNetworkCommissioningFeature>(ourTypeBits);
+
+    return self;
+}
+
+#pragma mark - NSCopying implementation
+
+- (id)copyWithZone:(nullable NSZone *)zone
+{
+    return self; // immutable
+}
+
+#pragma mark - NSSecureCoding implementation
+
++ (BOOL)supportsSecureCoding
+{
+    return YES;
+}
+
+static NSString * const sEndpointIDCodingKey = @"endpointID";
+static NSString * const sFeatureMapCodingKey = @"featureMap";
+
+- (void)encodeWithCoder:(NSCoder *)coder
+{
+    [coder encodeObject:self.endpointID forKey:sEndpointIDCodingKey];
+    [coder encodeObject:self.featureMap forKey:sFeatureMapCodingKey];
+}
+
+- (nullable instancetype)initWithCoder:(NSCoder *)coder
+{
+    NSNumber * endpointID = [coder decodeObjectOfClass:NSNumber.class forKey:sEndpointIDCodingKey];
+    NSNumber * featureMap = [coder decodeObjectOfClass:NSNumber.class forKey:sFeatureMapCodingKey];
+
+    if (endpointID == nil || featureMap == nil) {
+        return nil;
+    }
+
+    return [self initWithEndpointID:endpointID featureMap:featureMap];
+}
+
+#pragma mark - NSObject implementation
+
+- (NSUInteger)hash
+{
+    return self.endpointID.hash ^ self.featureMap.hash;
+}
+
+- (BOOL)isEqual:(id)object
+{
+    VerifyOrReturnValue([object class] == [self class], NO);
+
+    MTRNetworkInterfaceInfo * other = object;
+
+    VerifyOrReturnValue(MTREqualObjects(_endpointID, other->_endpointID), NO);
+    VerifyOrReturnValue(MTREqualObjects(_featureMap, other->_featureMap), NO);
+
+    return YES;
+}
+
+- (NSString *)description
+{
+    return [NSString stringWithFormat:@"<MTRNetworkInterfaceInfo: endpointID=%@, featureMap=0x%llx>",
+                     self.endpointID, self.featureMap.unsignedLongLongValue];
+}
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo_Internal.h b/src/darwin/Framework/CHIP/MTRNetworkInterfaceInfo_Internal.h
@@ -0,0 +1,31 @@
+/**
+ *    Copyright (c) 2025 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/MTRNetworkInterfaceInfo.h>
+
+#import "MTRDefines_Internal.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+MTR_DIRECT_MEMBERS
+@interface MTRNetworkInterfaceInfo ()
+
+// Will fail init if the featureMap claims multiple interface types.
+- (nullable instancetype)initWithEndpointID:(NSNumber *)endpointID featureMap:(NSNumber *)featureMap;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/darwin/Framework/CHIP/Matter.h b/src/darwin/Framework/CHIP/Matter.h
@@ -63,6 +63,7 @@
 #import <Matter/MTRLogging.h>
 #import <Matter/MTRManualSetupPayloadParser.h>
 #import <Matter/MTRMetrics.h>
+#import <Matter/MTRNetworkInterfaceInfo.h>
 #import <Matter/MTROTAHeader.h>
 #import <Matter/MTROTAProviderDelegate.h>
 #import <Matter/MTROnboardingPayloadParser.h>
diff --git a/src/darwin/Framework/CHIPTests/MTRPairingTests.m b/src/darwin/Framework/CHIPTests/MTRPairingTests.m
@@ -300,6 +300,8 @@ - (void)controller:(MTRDeviceController *)controller readCommissioneeInfo:(MTRCo
         XCTAssertEqualObjects(decoded.productIdentity, info.productIdentity);
         XCTAssertEqualObjects(decoded.endpointsById, info.endpointsById);
         XCTAssertEqualObjects(decoded.rootEndpoint.children, info.rootEndpoint.children);
+        XCTAssertEqualObjects(decoded.attributes, info.attributes);
+        XCTAssertEqualObjects(decoded.networkInterfaces, info.networkInterfaces);
     } else {
         XCTAssertNil(info.endpointsById);
         XCTAssertNil(info.rootEndpoint);
@@ -311,14 +313,26 @@ - (void)controller:(MTRDeviceController *)controller readCommissioneeInfo:(MTRCo
         return [path.cluster isEqual:@(MTRClusterIDTypeNetworkCommissioningID)] &&
             [path.attribute isEqual:@(MTRAttributeIDTypeGlobalAttributeFeatureMapID)];
     };
+    __auto_type endpointInList = ^(NSNumber * endpoint, NSArray<MTRNetworkInterfaceInfo *> * list) {
+        for (MTRNetworkInterfaceInfo * info in list) {
+            if ([info.endpointID isEqual:endpoint]) {
+                return YES;
+            }
+        }
+
+        return NO;
+    };
     NSUInteger networkCommissioningFeatureMapCount = 0;
     for (MTRAttributePath * path in info.attributes) {
         if (isNetworkCommissioningFeatureMap(path)) {
             ++networkCommissioningFeatureMapCount;
+            XCTAssertTrue(endpointInList(path.endpoint, info.networkInterfaces));
         }
     }
     XCTAssertGreaterThan(networkCommissioningFeatureMapCount, 0);
 
+    XCTAssertEqual(networkCommissioningFeatureMapCount, info.networkInterfaces.count);
+
     if (self.extraAttributesToRead) {
         // The attributes we tried to read should really have worked.
         XCTAssertNotNil(info.attributes);
diff --git a/src/darwin/Framework/Matter.xcodeproj/project.pbxproj b/src/darwin/Framework/Matter.xcodeproj/project.pbxproj
