Fix various miscellaneous Darwin API issues. (#22574)

* Rename readAttributeWithEndpointID to readAttributePathWithEndpointID
* Document readAttributePathWithEndpointID
* Rename subscribeAttributeWithEndpointID to subscribeAttributePathWithEndpointID
* Document subscribeAttributePathWithEndpointID
* Switch various things from "strong" to "copy" for paths, reports, etc.
* Remove redundant "nonnull" declarations on properties.
* Create typedefs for the NSData representations of certificates, for readability
* Replace "(nullable X *)" with "(X * _Nullable)" in various places.
* Fix various documentation.
* Rename "failSafeExpiryTimeoutSecs" to "failSafeExpiryTimeout".

Fixes #22531

Addresses part of #22420

Author: bzbarsky-apple

examples/darwin-framework-tool/commands/clusters/ReportCommandBridge.h

@@ -55,23 +55,23 @@ class ReadAttribute : public ModelCommand {
         dispatch_queue_t callbackQueue = dispatch_queue_create("com.chip.command", DISPATCH_QUEUE_SERIAL);
         MTRReadParams * params = [[MTRReadParams alloc] init];
         params.fabricFiltered = mFabricFiltered.HasValue() ? [NSNumber numberWithBool:mFabricFiltered.Value()] : nil;
-        [device
-            readAttributeWithEndpointID:[NSNumber numberWithUnsignedShort:endpointId]
-                              clusterID:[NSNumber numberWithUnsignedInteger:mClusterId]
-                            attributeID:[NSNumber numberWithUnsignedInteger:mAttributeId]
-                                 params:params
-                                  queue:callbackQueue
-                             completion:^(NSArray<NSDictionary<NSString *, id> *> * _Nullable values, NSError * _Nullable error) {
-                                 if (error != nil) {
-                                     LogNSError("Error reading attribute", error);
-                                 }
-                                 if (values) {
-                                     for (id item in values) {
-                                         NSLog(@"Response Item: %@", [item description]);
-                                     }
-                                 }
-                                 SetCommandExitStatus(error);
-                             }];
+        [device readAttributePathWithEndpointID:[NSNumber numberWithUnsignedShort:endpointId]
+                                      clusterID:[NSNumber numberWithUnsignedInteger:mClusterId]
+                                    attributeID:[NSNumber numberWithUnsignedInteger:mAttributeId]
+                                         params:params
+                                          queue:callbackQueue
+                                     completion:^(
+                                         NSArray<NSDictionary<NSString *, id> *> * _Nullable values, NSError * _Nullable error) {
+                                         if (error != nil) {
+                                             LogNSError("Error reading attribute", error);
+                                         }
+                                         if (values) {
+                                             for (id item in values) {
+                                                 NSLog(@"Response Item: %@", [item description]);
+                                             }
+                                         }
+                                         SetCommandExitStatus(error);
+                                     }];
         return CHIP_NO_ERROR;
     }
 
@@ -129,7 +129,7 @@ class SubscribeAttribute : public ModelCommand {
             = mKeepSubscriptions.HasValue() ? [NSNumber numberWithBool:mKeepSubscriptions.Value()] : nil;
         params.autoResubscribe = mAutoResubscribe.HasValue() ? [NSNumber numberWithBool:mAutoResubscribe.Value()] : nil;
 
-        [device subscribeAttributeWithEndpointID:[NSNumber numberWithUnsignedShort:endpointId]
+        [device subscribeAttributePathWithEndpointID:[NSNumber numberWithUnsignedShort:endpointId]
             clusterID:[NSNumber numberWithUnsignedInteger:mClusterId]
             attributeID:[NSNumber numberWithUnsignedInteger:mAttributeId]
             minInterval:[NSNumber numberWithUnsignedInteger:mMinInterval]

src/darwin/CHIPTool/CHIPTool/View Controllers/QRCode/QRCodeViewController.m

@@ -506,7 +506,7 @@ - (void)onPairingComplete:(NSError * _Nullable)error
         } else {
             MTRCommissioningParameters * params = [[MTRCommissioningParameters alloc] init];
             params.deviceAttestationDelegate = [[CHIPToolDeviceAttestationDelegate alloc] initWithViewController:self];
-            params.failSafeExpiryTimeoutSecs = @600;
+            params.failSafeExpiryTimeout = @600;
             NSError * error;
             if (![controller commissionDevice:deviceId commissioningParams:params error:&error]) {
                 NSLog(@"Failed to commission Device %llu, with error %@", deviceId, error);
@@ -674,7 +674,7 @@ - (void)commissionWithSSID:(NSString *)ssid password:(NSString *)password
     params.wifiSSID = [ssid dataUsingEncoding:NSUTF8StringEncoding];
     params.wifiCredentials = [password dataUsingEncoding:NSUTF8StringEncoding];
     params.deviceAttestationDelegate = [[CHIPToolDeviceAttestationDelegate alloc] initWithViewController:self];
-    params.failSafeExpiryTimeoutSecs = @600;
+    params.failSafeExpiryTimeout = @600;
 
     uint64_t deviceId = MTRGetNextAvailableDeviceID() - 1;
 

src/darwin/Framework/CHIP/MTRBaseDevice.h

@@ -184,14 +184,21 @@ extern NSString * const MTRArrayValueType;
     resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled;
 
 /**
- * Read attribute in a designated attribute path
+ * Reads the given attribute path from the device.
+ *
+ * nil values for endpointID, clusterID, attributeID indicate wildcards
+ * (e.g. nil attributeID means "read all the attributes from the endpoint(s) and
+ * cluster(s) that match endpointID/clusterID").
+ *
+ * A non-nil attributeID along with a nil clusterID will only succeed if the
+ * attribute ID is for a global attribute that applies to all clusters.
  */
-- (void)readAttributeWithEndpointID:(NSNumber * _Nullable)endpointID
-                          clusterID:(NSNumber * _Nullable)clusterID
-                        attributeID:(NSNumber * _Nullable)attributeID
-                             params:(MTRReadParams * _Nullable)params
-                              queue:(dispatch_queue_t)queue
-                         completion:(MTRDeviceResponseHandler)completion;
+- (void)readAttributePathWithEndpointID:(NSNumber * _Nullable)endpointID
+                              clusterID:(NSNumber * _Nullable)clusterID
+                            attributeID:(NSNumber * _Nullable)attributeID
+                                 params:(MTRReadParams * _Nullable)params
+                                  queue:(dispatch_queue_t)queue
+                             completion:(MTRDeviceResponseHandler)completion;
 
 /**
  * Write to attribute in a designated attribute path
@@ -203,8 +210,8 @@ extern NSString * const MTRArrayValueType;
  *
  * @param completion  response handler will receive either values or error.
  *
- *                    Received values are an NSArray object with response-value element as described in
- *                    readAttributeWithEndpointID:clusterID:attributeID:queue:completion:.
+ *                    Received values are documented in the definition of
+ *                    MTRDeviceResponseHandler.
  */
 - (void)writeAttributeWithEndpointID:(NSNumber *)endpointID
                            clusterID:(NSNumber *)clusterID
@@ -235,17 +242,24 @@ extern NSString * const MTRArrayValueType;
                          completion:(MTRDeviceResponseHandler)completion;
 
 /**
- * Subscribe an attribute in a designated attribute path
+ * Subscribes to the given attribute path on the device.
+ *
+ * nil values for endpointID, clusterID, attributeID indicate wildcards
+ * (e.g. nil attributeID means "read all the attributes from the endpoint(s) and
+ * cluster(s) that match endpointID/clusterID").
+ *
+ * A non-nil attributeID along with a nil clusterID will only succeed if the
+ * attribute ID is for a global attribute that applies to all clusters.
  */
-- (void)subscribeAttributeWithEndpointID:(NSNumber * _Nullable)endpointID
-                               clusterID:(NSNumber * _Nullable)clusterID
-                             attributeID:(NSNumber * _Nullable)attributeID
-                             minInterval:(NSNumber *)minInterval
-                             maxInterval:(NSNumber *)maxInterval
-                                  params:(MTRSubscribeParams * _Nullable)params
-                                   queue:(dispatch_queue_t)queue
-                           reportHandler:(MTRDeviceResponseHandler)reportHandler
-                 subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished;
+- (void)subscribeAttributePathWithEndpointID:(NSNumber * _Nullable)endpointID
+                                   clusterID:(NSNumber * _Nullable)clusterID
+                                 attributeID:(NSNumber * _Nullable)attributeID
+                                 minInterval:(NSNumber *)minInterval
+                                 maxInterval:(NSNumber *)maxInterval
+                                      params:(MTRSubscribeParams * _Nullable)params
+                                       queue:(dispatch_queue_t)queue
+                               reportHandler:(MTRDeviceResponseHandler)reportHandler
+                     subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished;
 
 /**
  * Deregister all local report handlers for a remote device
@@ -279,9 +293,9 @@ extern NSString * const MTRArrayValueType;
 @end
 
 @interface MTRAttributePath : NSObject <NSCopying>
-@property (nonatomic, readonly, strong, nonnull) NSNumber * endpoint;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * cluster;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * attribute;
+@property (nonatomic, readonly, copy) NSNumber * endpoint;
+@property (nonatomic, readonly, copy) NSNumber * cluster;
+@property (nonatomic, readonly, copy) NSNumber * attribute;
 
 + (instancetype)attributePathWithEndpointID:(NSNumber *)endpointID
                                   clusterID:(NSNumber *)clusterID
@@ -292,9 +306,9 @@ extern NSString * const MTRArrayValueType;
 @end
 
 @interface MTREventPath : NSObject
-@property (nonatomic, readonly, strong, nonnull) NSNumber * endpoint;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * cluster;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * event;
+@property (nonatomic, readonly, copy) NSNumber * endpoint;
+@property (nonatomic, readonly, copy) NSNumber * cluster;
+@property (nonatomic, readonly, copy) NSNumber * event;
 
 + (instancetype)eventPathWithEndpointID:(NSNumber *)endpointID clusterID:(NSNumber *)clusterID eventID:(NSNumber *)eventID;
 
@@ -303,9 +317,9 @@ extern NSString * const MTRArrayValueType;
 @end
 
 @interface MTRCommandPath : NSObject
-@property (nonatomic, readonly, strong, nonnull) NSNumber * endpoint;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * cluster;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * command;
+@property (nonatomic, readonly, copy) NSNumber * endpoint;
+@property (nonatomic, readonly, copy) NSNumber * cluster;
+@property (nonatomic, readonly, copy) NSNumber * command;
 
 + (instancetype)commandPathWithEndpointID:(NSNumber *)endpointID clusterID:(NSNumber *)clusterID commandID:(NSNumber *)commandID;
 
@@ -314,25 +328,27 @@ extern NSString * const MTRArrayValueType;
 @end
 
 @interface MTRAttributeReport : NSObject
-@property (nonatomic, readonly, strong, nonnull) MTRAttributePath * path;
+@property (nonatomic, readonly, copy) MTRAttributePath * path;
 // value is nullable because nullable attributes can have nil as value.
-@property (nonatomic, readonly, strong, nullable) id value;
+@property (nonatomic, readonly, copy, nullable) id value;
 // If this specific path resulted in an error, the error (in the
 // MTRInteractionErrorDomain or MTRErrorDomain) that corresponds to this
 // path.
-@property (nonatomic, readonly, strong, nullable) NSError * error;
+@property (nonatomic, readonly, copy, nullable) NSError * error;
 @end
 
 @interface MTREventReport : NSObject
-@property (nonatomic, readonly, strong, nonnull) MTREventPath * path;
-@property (nonatomic, readonly, strong, nonnull) NSNumber * eventNumber; // chip::EventNumber type (uint64_t)
-@property (nonatomic, readonly, strong, nonnull) NSNumber * priority; // chip::app::PriorityLevel type (uint8_t)
-@property (nonatomic, readonly, strong, nonnull) NSNumber * timestamp; // chip::app::Timestamp.mValue type (uint64_t)
-@property (nonatomic, readonly, strong, nullable) id value;
+@property (nonatomic, readonly, copy) MTREventPath * path;
+@property (nonatomic, readonly, copy) NSNumber * eventNumber; // EventNumber type (uint64_t)
+@property (nonatomic, readonly, copy) NSNumber * priority; // PriorityLevel type (uint8_t)
+@property (nonatomic, readonly, copy) NSNumber * timestamp; // Timestamp type (uint64_t)
+// An instance of one of the event payload interfaces.
+@property (nonatomic, readonly, copy) id value;
+
 // If this specific path resulted in an error, the error (in the
 // MTRInteractionErrorDomain or MTRErrorDomain) that corresponds to this
 // path.
-@property (nonatomic, readonly, strong, nullable) NSError * error;
+@property (nonatomic, readonly, copy, nullable) NSError * error;
 @end
 
 NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRBaseDevice.mm

@@ -301,7 +301,7 @@ - (void)invalidateCASESession
 - (void)subscribeWithQueue:(dispatch_queue_t)queue
                 minInterval:(NSNumber *)minInterval
                 maxInterval:(NSNumber *)maxInterval
-                     params:(nullable MTRSubscribeParams *)params
+                     params:(MTRSubscribeParams * _Nullable)params
     attributeCacheContainer:(MTRAttributeCacheContainer * _Nullable)attributeCacheContainer
      attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
          eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
@@ -771,12 +771,12 @@ void OnDeallocatePaths(chip::app::ReadPrepareParams && aReadPrepareParams) overr
     Platform::UniquePtr<app::ReadClient> mReadClient;
 };
 
-- (void)readAttributeWithEndpointID:(NSNumber *)endpointID
-                          clusterID:(NSNumber *)clusterID
-                        attributeID:(NSNumber *)attributeID
-                             params:(MTRReadParams * _Nullable)params
-                              queue:(dispatch_queue_t)queue
-                         completion:(MTRDeviceResponseHandler)completion
+- (void)readAttributePathWithEndpointID:(NSNumber * _Nullable)endpointID
+                              clusterID:(NSNumber * _Nullable)clusterID
+                            attributeID:(NSNumber * _Nullable)attributeID
+                                 params:(MTRReadParams * _Nullable)params
+                                  queue:(dispatch_queue_t)queue
+                             completion:(MTRDeviceResponseHandler)completion
 {
     endpointID = (endpointID == nil) ? nil : [endpointID copy];
     clusterID = (clusterID == nil) ? nil : [clusterID copy];
@@ -1114,15 +1114,15 @@ new MTRDataValueDictionaryCallbackBridge(queue, self, completion,
         });
 }
 
-- (void)subscribeAttributeWithEndpointID:(NSNumber * _Nullable)endpointID
-                               clusterID:(NSNumber * _Nullable)clusterID
-                             attributeID:(NSNumber * _Nullable)attributeID
-                             minInterval:(NSNumber *)minInterval
-                             maxInterval:(NSNumber *)maxInterval
-                                  params:(MTRSubscribeParams * _Nullable)params
-                                   queue:(dispatch_queue_t)queue
-                           reportHandler:(MTRDeviceResponseHandler)reportHandler
-                 subscriptionEstablished:(MTRSubscriptionEstablishedHandler)subscriptionEstablished
+- (void)subscribeAttributePathWithEndpointID:(NSNumber * _Nullable)endpointID
+                                   clusterID:(NSNumber * _Nullable)clusterID
+                                 attributeID:(NSNumber * _Nullable)attributeID
+                                 minInterval:(NSNumber *)minInterval
+                                 maxInterval:(NSNumber *)maxInterval
+                                      params:(MTRSubscribeParams * _Nullable)params
+                                       queue:(dispatch_queue_t)queue
+                               reportHandler:(MTRDeviceResponseHandler)reportHandler
+                     subscriptionEstablished:(MTRSubscriptionEstablishedHandler)subscriptionEstablished
 {
     if (self.isPASEDevice) {
         // We don't support subscriptions over PASE.
@@ -1525,6 +1525,11 @@ ConcreteEventPath path(static_cast<chip::EndpointId>([endpointID unsignedShortVa
 
     return [[MTREventPath alloc] initWithPath:path];
 }
+
+- (id)copyWithZone:(NSZone *)zone
+{
+    return [MTREventPath eventPathWithEndpointID:_endpoint clusterID:_cluster eventID:_event];
+}
 @end
 
 @implementation MTRCommandPath
@@ -1545,10 +1550,15 @@ ConcreteCommandPath path(static_cast<chip::EndpointId>([endpointID unsignedShort
 
     return [[MTRCommandPath alloc] initWithPath:path];
 }
+
+- (id)copyWithZone:(NSZone *)zone
+{
+    return [MTRCommandPath commandPathWithEndpointID:_endpoint clusterID:_cluster commandID:_command];
+}
 @end
 
 @implementation MTRAttributeReport
-- (instancetype)initWithPath:(const ConcreteDataAttributePath &)path value:(nullable id)value error:(nullable NSError *)error
+- (instancetype)initWithPath:(const ConcreteDataAttributePath &)path value:(id _Nullable)value error:(NSError * _Nullable)error
 {
     if (self = [super init]) {
         _path = [[MTRAttributePath alloc] initWithPath:path];
@@ -1564,8 +1574,8 @@ - (instancetype)initWithPath:(const ConcreteEventPath &)path
                  eventNumber:(NSNumber *)eventNumber
                     priority:(NSNumber *)priority
                    timestamp:(NSNumber *)timestamp
-                       value:(nullable id)value
-                       error:(nullable NSError *)error
+                       value:(id _Nullable)value
+                       error:(NSError * _Nullable)error
 {
     if (self = [super init]) {
         _path = [[MTREventPath alloc] initWithPath:path];

src/darwin/Framework/CHIP/MTRBaseDevice_Internal.h

@@ -75,17 +75,17 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface MTRAttributeReport ()
 - (instancetype)initWithPath:(const chip::app::ConcreteDataAttributePath &)path
-                       value:(nullable id)value
-                       error:(nullable NSError *)error;
+                       value:(id _Nullable)value
+                       error:(NSError * _Nullable)error;
 @end
 
 @interface MTREventReport ()
 - (instancetype)initWithPath:(const chip::app::ConcreteEventPath &)path
                  eventNumber:(NSNumber *)eventNumber
                     priority:(NSNumber *)priority
                    timestamp:(NSNumber *)timestamp
-                       value:(nullable id)value
-                       error:(nullable NSError *)error;
+                       value:(id _Nullable)value
+                       error:(NSError * _Nullable)error;
 @end
 
 // Exported utility function