[Darwin] MTRDevice should support multiple delegates (#32491)

* [Darwin] MTRDevice should support multiple delegates

* Better naming, comments, and removal of unused ivar

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.h

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Update src/darwin/Framework/CHIP/MTRDevice.mm

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

* Update src/darwin/Framework/CHIP/MTRDevice.mm

Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>

* Addressed review comments

* Address logging review comment

* Fix tests caused by new nullability change

* Fix unit test

---------

Co-authored-by: Justin Wood <woody@apple.com>
Co-authored-by: Karsten Sperling <113487422+ksperling-apple@users.noreply.github.com>
Co-authored-by: Boris Zbarsky <bzbarsky@apple.com>

Author: 4 people

src/darwin/Framework/CHIP/MTRDevice.h

@@ -114,7 +114,36 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
  *
  * The delegate will be called on the provided queue, for attribute reports, event reports, and device state changes.
  */
-- (void)setDelegate:(id<MTRDeviceDelegate>)delegate queue:(dispatch_queue_t)queue;
+- (void)setDelegate:(id<MTRDeviceDelegate>)delegate queue:(dispatch_queue_t)queue MTR_NEWLY_DEPRECATED("Please use addDelegate:queue:interestedPaths:");
+
+/**
+ * Adds a delegate to receive asynchronous callbacks about the device.
+ *
+ * The delegate will be called on the provided queue, for attribute reports, event reports, and device state changes.
+ *
+ * MTRDevice holds a weak reference to the delegate object.
+ */
+- (void)addDelegate:(id<MTRDeviceDelegate>)delegate queue:(dispatch_queue_t)queue MTR_NEWLY_AVAILABLE;
+
+/**
+ * Adds a delegate to receive asynchronous callbacks about the device, and limit attribute and/or event reports to a specific set of paths.
+ *
+ * interestedPathsForAttributes may contain either MTRClusterPath or MTRAttributePath to specify interested clusters and attributes, or NSNumber for endpoints.
+ *
+ * interestedPathsForAttributes may contain either MTRClusterPath or MTREventPath to specify interested clusters and events, or NSNumber for endpoints.
+ *
+ * For both interested paths arguments, if nil is specified, then no filter will be applied.
+ *
+ * Calling addDelegate: again with the same delegate object will update the interested paths for attributes and events for this delegate.
+ *
+ * MTRDevice holds a weak reference to the delegate object.
+ */
+- (void)addDelegate:(id<MTRDeviceDelegate>)delegate queue:(dispatch_queue_t)queue interestedPathsForAttributes:(NSArray * _Nullable)interestedPathsForAttributes interestedPathsForEvents:(NSArray * _Nullable)interestedPathsForEvents MTR_NEWLY_AVAILABLE;
+
+/**
+ * Removes the delegate from receiving callbacks about the device.
+ */
+- (void)removeDelegate:(id<MTRDeviceDelegate>)delegate MTR_NEWLY_AVAILABLE;
 
 /**
  * Read attribute in a designated attribute path.  If there is no value available
@@ -389,7 +418,7 @@ MTR_EXTERN NSString * const MTRDataVersionKey MTR_AVAILABLE(ios(17.6), macos(14.
  *
  *                The data-value dictionary also contains this key:
  *
- *                MTRDataVersionKey : NSNumber-wrapped uin32_t. Monotonically increaseing data version for the cluster.
+ *                MTRDataVersionKey : NSNumber-wrapped uin32_t.
  */
 - (void)device:(MTRDevice *)device receivedAttributeReport:(NSArray<NSDictionary<NSString *, id> *> *)attributeReport;