Add better APIs for handling FeatureMap in MTRServerAttribute. (#33760)

* Add better APIs for handling FeatureMap in MTRServerAttribute.

Do more sanity checks when using the initializer, and provide a factory method
that makes creating FeatureMap attributes easier.

* Apply suggestions from code review

Co-authored-by: Nivi Sarkar <[email protected]>

---------

Co-authored-by: Nivi Sarkar <[email protected]>

src/darwin/Framework/CHIP/ServerEndpoint/MTRServerAttribute.h

@@ -41,7 +41,9 @@ MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6))
  * Will fail if the attribute ID is not valid per the Matter specification or
  * the attribute value is not a valid data-value.
  *
- * requiredPrivilege is the privilege required to read the attribute.
+ * requiredPrivilege is the privilege required to read the attribute. This
+ * initializer may fail if the provided attributeID is a global attribute and
+ * the provided requiredPrivilege value is not correct for that attribute ID.
  */
 - (nullable instancetype)initReadonlyAttributeWithID:(NSNumber *)attributeID initialValue:(NSDictionary<NSString *, id> *)value requiredPrivilege:(MTRAccessControlEntryPrivilege)requiredPrivilege;
 
@@ -53,6 +55,14 @@ MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6))
  */
 - (BOOL)setValue:(NSDictionary<NSString *, id> *)value;
 
+/**
+ * Create an attribute description for a FeatureMap attribute with the provided
+ * value (expected to be an unsigned integer representing the value of the
+ * bitmap). This will automatically set requiredPrivilege to the right value
+ * for FeatureMap.
+ */
++ (MTRServerAttribute *)newFeatureMapAttributeWithInitialValue:(NSNumber *)value;
+
 @property (atomic, copy, readonly) NSNumber * attributeID;
 @property (atomic, copy, readonly) NSDictionary<NSString *, id> * value;
 /**

src/darwin/Framework/CHIP/ServerEndpoint/MTRServerAttribute.mm

@@ -23,6 +23,7 @@
 #import "MTRUnfairLock.h"
 #import "NSDataSpanConversion.h"
 
+#import <Matter/MTRClusterConstants.h>
 #import <Matter/MTRServerAttribute.h>
 
 #include <app/reporting/reporting.h>
@@ -57,6 +58,20 @@ - (nullable instancetype)initAttributeWithID:(NSNumber *)attributeID initialValu
  return nil;
  }
 
+ if (attrId == MTRAttributeIDTypeGlobalAttributeFeatureMapID) {
+ // Some sanity checks: value should be an unsigned-integer NSNumber, and
+ // requiredReadPrivilege should be View.
+ if (requiredReadPrivilege != MTRAccessControlEntryPrivilegeView) {
+ MTR_LOG_ERROR("MTRServerAttribute for FeatureMap provided with invalid read privilege %d", requiredReadPrivilege);
+ return nil;
+ }
+
+ if (![MTRUnsignedIntegerValueType isEqual:value[MTRTypeKey]]) {
+ MTR_LOG_ERROR("MTRServerAttribute for FeatureMap provided with value that is not an unsigned integer: %@", value);
+ return nil;
+ }
+ }
+
  return [self initWithAttributeID:[attributeID copy] value:[value copy] requiredReadPrivilege:requiredReadPrivilege writable:writable];
 }
 
@@ -80,7 +95,8 @@ - (nullable instancetype)initWithAttributeID:(NSNumber *)attributeID value:(NSDi
  _writable = writable;
  _parentCluster = app::ConcreteClusterPath(kInvalidEndpointId, kInvalidClusterId);
 
- // Now call setValue to store the value and its serialization.
+ // Now store the value and its serialization. This will also check that the
+ // value is serializable to TLV.
  if ([self setValueInternal:value logIfNotAssociated:NO] == NO) {
  return nil;
  }
@@ -93,6 +109,16 @@ - (BOOL)setValue:(NSDictionary<NSString *, id> *)value
  return [self setValueInternal:value logIfNotAssociated:YES];
 }
 
++ (MTRServerAttribute *)newFeatureMapAttributeWithInitialValue:(NSNumber *)value
+{
+ return [[MTRServerAttribute alloc] initReadonlyAttributeWithID:@(MTRAttributeIDTypeGlobalAttributeFeatureMapID)
+ initialValue:@{
+ MTRTypeKey : MTRUnsignedIntegerValueType,
+ MTRValueKey : value,
+ }
+ requiredPrivilege:MTRAccessControlEntryPrivilegeView];
+}
+
 - (BOOL)setValueInternal:(NSDictionary<NSString *, id> *)value logIfNotAssociated:(BOOL)logIfNotAssociated
 {
  id serializedValue;

src/darwin/Framework/CHIPTests/MTRServerEndpointTests.m

@@ -126,6 +126,11 @@ - (void)testServerAttribute
  MTRValueKey : @(5),
  };
 
+ __auto_type * signedIntValue = @{
+ MTRTypeKey : MTRSignedIntegerValueType,
+ MTRValueKey : @(5),
+ };
+
  __auto_type * listOfStringsValue = @{
  MTRTypeKey : MTRArrayValueType,
  MTRValueKey : @[
@@ -192,6 +197,36 @@ - (void)testServerAttribute
  __auto_type * attr = [[MTRServerAttribute alloc] initReadonlyAttributeWithID:invalidID initialValue:unsignedIntValue requiredPrivilege:MTRAccessControlEntryPrivilegeView];
  XCTAssertNil(attr);
  }
+
+ // Valid FeatureMap attribute
+ {
+ __auto_type * attr = [[MTRServerAttribute alloc] initReadonlyAttributeWithID:@(MTRAttributeIDTypeGlobalAttributeFeatureMapID) initialValue:unsignedIntValue requiredPrivilege:MTRAccessControlEntryPrivilegeView];
+ XCTAssertNotNil(attr);
+ XCTAssertEqualObjects(attr.attributeID, @(MTRAttributeIDTypeGlobalAttributeFeatureMapID));
+ XCTAssertEqualObjects(attr.value, unsignedIntValue);
+ XCTAssertEqual(attr.writable, NO);
+ }
+
+ // FeatureMap attribute with wrong value type
+ {
+ __auto_type * attr = [[MTRServerAttribute alloc] initReadonlyAttributeWithID:@(MTRAttributeIDTypeGlobalAttributeFeatureMapID) initialValue:signedIntValue requiredPrivilege:MTRAccessControlEntryPrivilegeView];
+ XCTAssertNil(attr);
+ }
+
+ // FeatureMap attribute with wrong permissions
+ {
+ __auto_type * attr = [[MTRServerAttribute alloc] initReadonlyAttributeWithID:@(MTRAttributeIDTypeGlobalAttributeFeatureMapID) initialValue:unsignedIntValue requiredPrivilege:MTRAccessControlEntryPrivilegeOperate];
+ XCTAssertNil(attr);
+ }
+
+ // FeatureMap attribute via factory
+ {
+ __auto_type * attr = [MTRServerAttribute newFeatureMapAttributeWithInitialValue:@(5)];
+ XCTAssertNotNil(attr);
+ XCTAssertEqualObjects(attr.attributeID, @(MTRAttributeIDTypeGlobalAttributeFeatureMapID));
+ XCTAssertEqualObjects(attr.value, unsignedIntValue);
+ XCTAssertEqual(attr.writable, NO);
+ }
 }
 
 - (void)testDeviceType