Fix API review comments for MTRAttributeCacheContainer. (#23639)

This is a re-landing of PR #22636 but with changes made for backwards compat.

* Fix function naming to indicate we may be reading a multiple
  attributes, not just an attribute.
* Fix documentation.
* Rename to MTRClusterStateCacheContainer.

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

@@ -208,7 +208,7 @@ class SubscribeEvent : public ModelCommand {
 
         [device subscribeWithQueue:callbackQueue
             params:params
-            attributeCacheContainer:nil
+            clusterStateCacheContainer:nil
             attributeReportHandler:^(NSArray * value) {
                 SetCommandExitStatus(CHIP_NO_ERROR);
             }

src/darwin/Framework/CHIP/MTRBaseDevice.h

@@ -117,6 +117,7 @@ extern NSString * const MTRNullValueType;
 extern NSString * const MTRStructureValueType;
 extern NSString * const MTRArrayValueType;
 
+@class MTRClusterStateCacheContainer;
 @class MTRAttributeCacheContainer;
 @class MTRReadParams;
 @class MTRSubscribeParams;
@@ -174,13 +175,13 @@ extern NSString * const MTRArrayValueType;
  * attempts fail.
  */
 - (void)subscribeWithQueue:(dispatch_queue_t)queue
-                     params:(MTRSubscribeParams *)params
-    attributeCacheContainer:(MTRAttributeCacheContainer * _Nullable)attributeCacheContainer
-     attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
-         eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
-               errorHandler:(MTRDeviceErrorHandler)errorHandler
-    subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
-    resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled MTR_NEWLY_AVAILABLE;
+                        params:(MTRSubscribeParams *)params
+    clusterStateCacheContainer:(MTRClusterStateCacheContainer * _Nullable)clusterStateCacheContainer
+        attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
+            eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
+                  errorHandler:(MTRDeviceErrorHandler)errorHandler
+       subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
+       resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled MTR_NEWLY_AVAILABLE;
 
 /**
  * Reads attributes from the device.
@@ -403,9 +404,10 @@ MTR_NEWLY_AVAILABLE
                errorHandler:(MTRDeviceErrorHandler)errorHandler
     subscriptionEstablished:(dispatch_block_t _Nullable)subscriptionEstablishedHandler
     resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduledHandler
-    MTR_NEWLY_DEPRECATED("Please use "
-                         "subscribeWithQueue:params:attributeCacheContainer:attributeReportHandler:eventReportHandler:errorHandler:"
-                         "subscriptionEstablished:resubscriptionScheduled:");
+    MTR_NEWLY_DEPRECATED(
+        "Please use "
+        "subscribeWithQueue:params:clusterStateCacheContainer:attributeReportHandler:eventReportHandler:errorHandler:"
+        "subscriptionEstablished:resubscriptionScheduled:");
 
 - (void)readAttributeWithEndpointId:(NSNumber * _Nullable)endpointId
                           clusterId:(NSNumber * _Nullable)clusterId

src/darwin/Framework/CHIP/MTRBaseDevice.mm

@@ -15,12 +15,12 @@
  *    limitations under the License.
  */
 
-#import "MTRAttributeCacheContainer_Internal.h"
 #import "MTRAttributeTLVValueDecoder_Internal.h"
 #import "MTRBaseDevice_Internal.h"
 #import "MTRBaseSubscriptionCallback.h"
 #import "MTRCallbackBridgeBase_internal.h"
 #import "MTRCluster.h"
+#import "MTRClusterStateCacheContainer_Internal.h"
 #import "MTRCluster_internal.h"
 #import "MTRError_Internal.h"
 #import "MTREventTLVValueDecoder_Internal.h"
@@ -268,13 +268,13 @@ - (void)invalidateCASESession
 } // anonymous namespace
 
 - (void)subscribeWithQueue:(dispatch_queue_t)queue
-                     params:(MTRSubscribeParams *)params
-    attributeCacheContainer:(MTRAttributeCacheContainer * _Nullable)attributeCacheContainer
-     attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
-         eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
-               errorHandler:(void (^)(NSError * error))errorHandler
-    subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
-    resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled
+                        params:(MTRSubscribeParams *)params
+    clusterStateCacheContainer:(MTRClusterStateCacheContainer * _Nullable)clusterStateCacheContainer
+        attributeReportHandler:(MTRDeviceReportHandler _Nullable)attributeReportHandler
+            eventReportHandler:(MTRDeviceReportHandler _Nullable)eventReportHandler
+                  errorHandler:(void (^)(NSError * error))errorHandler
+       subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
+       resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled
 {
     if (self.isPASEDevice) {
         // We don't support subscriptions over PASE.
@@ -309,18 +309,18 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
                                       readParams.mpEventPathParamsList = eventPath.get();
                                       readParams.mEventPathParamsListSize = 1;
 
-                                      std::unique_ptr<ClusterStateCache> attributeCache;
+                                      std::unique_ptr<ClusterStateCache> clusterStateCache;
                                       ReadClient::Callback * callbackForReadClient = nullptr;
                                       OnDoneHandler onDoneHandler = nil;
 
-                                      if (attributeCacheContainer) {
-                                          __weak MTRAttributeCacheContainer * weakPtr = attributeCacheContainer;
+                                      if (clusterStateCacheContainer) {
+                                          __weak MTRClusterStateCacheContainer * weakPtr = clusterStateCacheContainer;
                                           onDoneHandler = ^{
                                               // This, like all manipulation of cppClusterStateCache, needs to run on the Matter
                                               // queue.
-                                              MTRAttributeCacheContainer * container = weakPtr;
+                                              MTRClusterStateCacheContainer * container = weakPtr;
                                               if (container) {
-                                                  container.cppAttributeCache = nullptr;
+                                                  container.cppClusterStateCache = nullptr;
                                               }
                                           };
                                       }
@@ -361,9 +361,9 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
                                           },
                                           onDoneHandler);
 
-                                      if (attributeCacheContainer) {
-                                          attributeCache = std::make_unique<ClusterStateCache>(*callback.get());
-                                          callbackForReadClient = &attributeCache->GetBufferedCallback();
+                                      if (clusterStateCacheContainer) {
+                                          clusterStateCache = std::make_unique<ClusterStateCache>(*callback.get());
+                                          callbackForReadClient = &clusterStateCache->GetBufferedCallback();
                                       } else {
                                           callbackForReadClient = &callback->GetBufferedCallback();
                                       }
@@ -389,14 +389,12 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
                                           return;
                                       }
 
-                                      if (attributeCacheContainer) {
-                                          attributeCacheContainer.cppAttributeCache = attributeCache.get();
-                                          // ClusterStateCache will be deleted when OnDone is called or an error is encountered as
-                                          // well.
-                                          callback->AdoptAttributeCache(std::move(attributeCache));
+                                      if (clusterStateCacheContainer) {
+                                          clusterStateCacheContainer.cppClusterStateCache = clusterStateCache.get();
+                                          // ClusterStateCache will be deleted when OnDone is called.
+                                          callback->AdoptClusterStateCache(std::move(clusterStateCache));
                                       }
-                                      // Callback and ReadClient will be deleted when OnDone is called or an error is
-                                      // encountered.
+                                      // Callback and ReadClient will be deleted when OnDone is called.
                                       callback->AdoptReadClient(std::move(readClient));
                                       callback.release();
                                   }];
@@ -1458,13 +1456,13 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
         subscribeParams.maxInterval = @(maxInterval);
     }
     [self subscribeWithQueue:queue
-                         params:subscribeParams
-        attributeCacheContainer:attributeCacheContainer
-         attributeReportHandler:attributeReportHandler
-             eventReportHandler:eventReportHandler
-                   errorHandler:errorHandler
-        subscriptionEstablished:subscriptionEstablishedHandler
-        resubscriptionScheduled:resubscriptionScheduledHandler];
+                            params:subscribeParams
+        clusterStateCacheContainer:attributeCacheContainer.realContainer
+            attributeReportHandler:attributeReportHandler
+                eventReportHandler:eventReportHandler
+                      errorHandler:errorHandler
+           subscriptionEstablished:subscriptionEstablishedHandler
+           resubscriptionScheduled:resubscriptionScheduledHandler];
 }
 
 - (void)readAttributeWithEndpointId:(NSNumber * _Nullable)endpointId

src/darwin/Framework/CHIP/MTRBaseSubscriptionCallback.h

@@ -82,9 +82,9 @@ class MTRBaseSubscriptionCallback : public chip::app::ClusterStateCache::Callbac
 
     // We need to exist to get a ReadClient, so can't take this as a constructor argument.
     void AdoptReadClient(std::unique_ptr<chip::app::ReadClient> aReadClient) { mReadClient = std::move(aReadClient); }
-    void AdoptAttributeCache(std::unique_ptr<chip::app::ClusterStateCache> aAttributeCache)
+    void AdoptClusterStateCache(std::unique_ptr<chip::app::ClusterStateCache> aClusterStateCache)
     {
-        mAttributeCache = std::move(aAttributeCache);
+        mClusterStateCache = std::move(aClusterStateCache);
     }
 
 protected:
@@ -150,7 +150,7 @@ class MTRBaseSubscriptionCallback : public chip::app::ClusterStateCache::Callbac
     //    from OnDone or from an error callback but not both, by tracking whether
     //    we have a queued-up deletion.
     std::unique_ptr<chip::app::ReadClient> mReadClient;
-    std::unique_ptr<chip::app::ClusterStateCache> mAttributeCache;
+    std::unique_ptr<chip::app::ClusterStateCache> mClusterStateCache;
     bool mHaveQueuedDeletion = false;
     OnDoneHandler _Nullable mOnDoneHandler = nil;
 };

src/darwin/Framework/CHIP/MTRAttributeCacheContainer+XPC.h → src/darwin/Framework/CHIP/MTRClusterStateCacheContainer+XPC.h

@@ -17,11 +17,11 @@
 
 #import <Foundation/Foundation.h>
 
-#import "MTRAttributeCacheContainer.h"
+#import "MTRClusterStateCacheContainer.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
-@interface MTRAttributeCacheContainer (XPC)
+@interface MTRClusterStateCacheContainer (XPC)
 - (void)setXPCConnection:(MTRDeviceControllerXPCConnection *)xpcConnection
             controllerID:(id<NSCopying>)controllerID
                 deviceID:(NSNumber *)deviceID;

src/darwin/Framework/CHIP/MTRAttributeCacheContainer.h → src/darwin/Framework/CHIP/MTRClusterStateCacheContainer.h

@@ -24,35 +24,45 @@ NS_ASSUME_NONNULL_BEGIN
 
 @class MTRSubscribeParams;
 
-@interface MTRAttributeCacheContainer : NSObject
+/**
+ * An object that holds a cluster state cache.  It can be passed to
+ * MTRBaseDevice's subscribeWithQueue to fill the cache with data the
+ * subscription returns.  Then reads can happen against the cache without going
+ * out to the network.
+ */
+MTR_NEWLY_AVAILABLE
+@interface MTRClusterStateCacheContainer : NSObject
 
 /**
- * Reads an attribute with specific attribute path
+ * Reads the given attributes from the cluster state cache inside
+ * this cache container.
  *
- * @param endpointID  endpoint ID of the attribute
- * @param clusterID  cluster ID of the attribute
- * @param attributeID  attribute ID of the attribute
+ * @param endpointID  endpoint ID of the attributes. Nil means wildcard.
+ * @param clusterID  cluster ID of the attributes. Nil means wildcard.
+ * @param attributeID  attribute ID of the attributes. Nil means wildcard.
  * @param queue  client queue to dispatch the completion handler through
  * @param completion  block to receive the result.
- *                   "values" received by the block will have the same format of object as the one received by completion block
- *                   of MTRBaseDevice readAttributeWithEndpointID:clusterID:attributeID:queue:completion method.
+ *                   "values" received by the block will have the same format of object as the one received by the completion block
+ *                   of the MTRBaseDevice readAttributesWithEndpointID:clusterID:attributeID:queue:completion method.
+ *
+ * @note: not all combinations of wildcards might be supported.
  */
-- (void)readAttributeWithEndpointID:(NSNumber * _Nullable)endpointID
-                          clusterID:(NSNumber * _Nullable)clusterID
-                        attributeID:(NSNumber * _Nullable)attributeID
-                              queue:(dispatch_queue_t)queue
-                         completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
+- (void)readAttributesWithEndpointID:(NSNumber * _Nullable)endpointID
+                           clusterID:(NSNumber * _Nullable)clusterID
+                         attributeID:(NSNumber * _Nullable)attributeID
+                               queue:(dispatch_queue_t)queue
+                          completion:(MTRDeviceResponseHandler)completion;
 
 @end
 
-@interface MTRAttributeCacheContainer (Deprecated)
+MTR_NEWLY_DEPRECATED("Please use MTRClusterStateCacheContainer")
+@interface MTRAttributeCacheContainer : NSObject
 
 - (void)readAttributeWithEndpointId:(NSNumber * _Nullable)endpointId
                           clusterId:(NSNumber * _Nullable)clusterId
                         attributeId:(NSNumber * _Nullable)attributeId
                         clientQueue:(dispatch_queue_t)clientQueue
-                         completion:(MTRDeviceResponseHandler)completion
-    MTR_NEWLY_DEPRECATED("Please use readAttributeWithEndpointID:clusterID:attributeID:queue:completion:");
+                         completion:(MTRDeviceResponseHandler)completion;
 
 @end