Fix API review comments for MTRAttributeCacheContainer.

* Fix function naming to indicate we are reading a path (maybe multiple
  attributes), not just an attribute.
* Fix documentation.
* Rename to MTRClusterStateCacheContainer.

Fixes project-chip#22532

Addresses part of project-chip#22420

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/CHIPTool/CHIPTool/View Controllers/Temperature Sensor/TemperatureSensorViewController.m

@@ -226,7 +226,7 @@ - (void)reportFromUserEnteredSettings
                                                                            maxInterval:@(maxIntervalSeconds)];
                 [chipDevice subscribeWithQueue:dispatch_get_main_queue()
                     params:params
-                    attributeCacheContainer:nil
+                    clusterStateCacheContainer:nil
                     attributeReportHandler:^(NSArray * _Nullable reports) {
                         if (!reports)
                             return;

src/darwin/Framework/CHIP/MTRBaseDevice.h

@@ -115,7 +115,7 @@ extern NSString * const MTRNullValueType;
 extern NSString * const MTRStructureValueType;
 extern NSString * const MTRArrayValueType;
 
-@class MTRAttributeCacheContainer;
+@class MTRClusterStateCacheContainer;
 @class MTRReadParams;
 @class MTRSubscribeParams;
 @class MTRDeviceController;
@@ -173,13 +173,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;
+                        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;
 
 /**
  * Reads the given attribute path from the device.

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 "MTRError_Internal.h"
 #import "MTREventTLVValueDecoder_Internal.h"
 #import "MTRLogging.h"
@@ -299,13 +299,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.
@@ -344,19 +344,19 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
 
                    std::unique_ptr<SubscriptionCallback> callback;
                    std::unique_ptr<ReadClient> readClient;
-                   std::unique_ptr<ClusterStateCache> attributeCache;
-                   if (attributeCacheContainer) {
-                       __weak MTRAttributeCacheContainer * weakPtr = attributeCacheContainer;
+                   std::unique_ptr<ClusterStateCache> clusterStateCache;
+                   if (clusterStateCacheContainer) {
+                       __weak MTRClusterStateCacheContainer * weakPtr = clusterStateCacheContainer;
                        callback = std::make_unique<SubscriptionCallback>(queue, attributeReportHandler, eventReportHandler,
                            errorHandler, resubscriptionScheduled, subscriptionEstablished, ^{
-                               MTRAttributeCacheContainer * container = weakPtr;
+                               MTRClusterStateCacheContainer * container = weakPtr;
                                if (container) {
-                                   container.cppAttributeCache = nullptr;
+                                   container.cppClusterStateCache = nullptr;
                                }
                            });
-                       attributeCache = std::make_unique<ClusterStateCache>(*callback.get());
+                       clusterStateCache = std::make_unique<ClusterStateCache>(*callback.get());
                        readClient = std::make_unique<ReadClient>(InteractionModelEngine::GetInstance(), exchangeManager,
-                           attributeCache->GetBufferedCallback(), ReadClient::InteractionType::Subscribe);
+                           clusterStateCache->GetBufferedCallback(), ReadClient::InteractionType::Subscribe);
                    } else {
                        callback = std::make_unique<SubscriptionCallback>(queue, attributeReportHandler, eventReportHandler,
                            errorHandler, resubscriptionScheduled, subscriptionEstablished, nil);
@@ -382,10 +382,10 @@ - (void)subscribeWithQueue:(dispatch_queue_t)queue
                        return;
                    }
 
-                   if (attributeCacheContainer) {
-                       attributeCacheContainer.cppAttributeCache = attributeCache.get();
+                   if (clusterStateCacheContainer) {
+                       clusterStateCacheContainer.cppClusterStateCache = clusterStateCache.get();
                        // ClusterStateCache will be deleted when OnDone is called or an error is encountered as well.
-                       callback->AdoptAttributeCache(std::move(attributeCache));
+                       callback->AdoptClusterStateCache(std::move(clusterStateCache));
                    }
                    // Callback and ReadClient will be deleted when OnDone is called or an error is
                    // encountered.

src/darwin/Framework/CHIP/MTRBaseSubscriptionCallback.h

@@ -75,9 +75,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:
@@ -142,7 +142,7 @@ class MTRBaseSubscriptionCallback : public chip::app::ClusterStateCache::Callbac
     //    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/MTRClusterStateCacheContainer.h

@@ -0,0 +1,57 @@
+/**
+ *
+ *    Copyright (c) 2022 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import <Matter/MTRBaseDevice.h>
+#import <Matter/MTRDeviceController.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class MTRSubscribeParams;
+
+/**
+ * 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.
+ */
+@interface MTRClusterStateCacheContainer : NSObject
+
+/**
+ * Reads the given attribute path from the cluster state cache inside
+ * this cache container.
+ *
+ * @param endpointID  endpoint ID of the attribute.  nil means wildcard.
+ * @param clusterID  cluster ID of the attribute  nil means wildcard.
+ * @param attributeID  attribute ID of the attribute.  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 the completion block
+ *                   of the MTRBaseDevice readAttributePathWithEndpointID:clusterID:attributeID:queue:completion method.
+ *
+ * @note: not all combinations of wildcards might be supported.
+ */
+- (void)readAttributePathWithEndpointID:(NSNumber * _Nullable)endpointID
+                              clusterID:(NSNumber * _Nullable)clusterID
+                            attributeID:(NSNumber * _Nullable)attributeID
+                                  queue:(dispatch_queue_t)queue
+                             completion:(MTRDeviceResponseHandler)completion;
+
+@end
+
+NS_ASSUME_NONNULL_END