Fix various miscellaneous Darwin API issues.

This is a re-landing of PR project-chip#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". The nullable to _Nullable change we might want to undo, but keeping it for now to make re-landing other PRs that were on top of project-chip#22574 easier. The header changes not accompanied by backwards-compat shims are OK for the following reasons: * The changes to MTRBaseDevice.h are all to MTR_NEWLY_AVAILABLE APIs or fixing obvious API bugs (replacing "strong" with "copy"). * MTRBaseDevice_Internal.h is not public API. * The changes to MTRCertificates.h are all to MTR_NEWLY_AVAILABLE APIs or are source+binary compatible. * The changes to MTRCluster.h are source+binary compatible. * MTRCluster_internal.h is not public API. * The changes to MTRDeviceController.h are source+binary compatible. * The changes to MTRDeviceControllerStartupParams.h are source+binary compatible. * MTRDeviceControllerStartupParams_Internal.h is not public API. * The changes to MTRDevicePairingDelegate.h are source+binary compatible. * The changes to MTRError.h are source+binary compatible. * MTRError_Internal.h is not public API. * The changes to MTRManualSetupPayloadParser.h are source+binary compatible. * The changes to MTROnboardingPayloadParser.h are source+binary compatible. * The changes to MTRPersistentStorageDelegate.h are source+binary compatible. * The changes to MTRQRCodeSetupPayloadParser.h are source+binary compatible. * The changes to MTRSetupPayload.h are source+binary compatible. * The changes to MTRThreadOperationalDataset.h are source+binary compatible. * The changes to MTRBaseClusters.h are source+binary compatible. * The changes to MTRClusters.h are source+binary compatible. * The changes to MTRCommandPayloadsObjc.h are source+binary compatible. * The changes to MTRStructsObjc.h are source+binary compatible.
bzbarsky-apple · Nov 4, 2022 · a817c67 · a817c67
1 parent 42b4438
commit a817c67
Show file tree

Hide file tree

Showing 47 changed files with 1,873 additions and 1,798 deletions.
diff --git a/examples/darwin-framework-tool/commands/clusters/ReportCommandBridge.h b/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]

diff --git a/src/darwin/Framework/CHIP/MTRBaseDevice.h b/src/darwin/Framework/CHIP/MTRBaseDevice.h
@@ -176,14 +176,21 @@ extern NSString * const MTRArrayValueType;
     resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled MTR_NEWLY_AVAILABLE;
 
 /**
- * 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 MTR_NEWLY_AVAILABLE;
+- (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 MTR_NEWLY_AVAILABLE;
 
 /**
  * Write to attribute in a designated attribute path
@@ -195,8 +202,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
@@ -227,17 +234,25 @@ extern NSString * const MTRArrayValueType;
                          completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
 
 /**
- * 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 MTR_NEWLY_AVAILABLE;
+- (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
+    MTR_NEWLY_AVAILABLE;
 
 /**
  * Deregister all local report handlers for a remote device
@@ -272,9 +287,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
@@ -285,9 +300,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
@@ -298,9 +313,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
@@ -311,25 +326,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
 
 @interface MTRBaseDevice (Deprecated)
@@ -357,7 +374,7 @@ extern NSString * const MTRArrayValueType;
                              params:(MTRReadParams * _Nullable)params
                         clientQueue:(dispatch_queue_t)clientQueue
                          completion:(MTRDeviceResponseHandler)completion
-    MTR_NEWLY_DEPRECATED("Please use readAttributeWithEndpointID:clusterID:attributeID:params:queue:completion:");
+    MTR_NEWLY_DEPRECATED("Please use readAttributePathWithEndpointID:clusterID:attributeID:params:queue:completion:");
 
 - (void)writeAttributeWithEndpointId:(NSNumber *)endpointId
                            clusterId:(NSNumber *)clusterId
@@ -387,9 +404,9 @@ extern NSString * const MTRArrayValueType;
                              clientQueue:(dispatch_queue_t)clientQueue
                            reportHandler:(MTRDeviceResponseHandler)reportHandler
                  subscriptionEstablished:(dispatch_block_t _Nullable)subscriptionEstablishedHandler
-    MTR_NEWLY_DEPRECATED(
-        "Please use "
-        "subscribeAttributeWithEndpointID:clusterID:attributeID:params:minInterval:maxInterval:queue:reportHandler:");
+    MTR_NEWLY_DEPRECATED("Please use "
+                         "subscribeAttributePathWithEndpointID:clusterID:attributeID:params:minInterval:maxInterval:queue:"
+                         "reportHandler:subscriptionEstablished:");
 
 - (void)deregisterReportHandlersWithClientQueue:(dispatch_queue_t)queue
                                      completion:(dispatch_block_t)completion