Add a Matter.framework API for invoking multiple commands. (project-chip#37398)

* Add a Matter.framework API for invoking multiple commands.

The API allows grouping the commands, so that later groups don't get invoked if
anything in an earlier group fails.

The changes to _invokeCommandWithEndpointID in MTRDevice_XPC.mm are fixing a
pre-existing bug where it was not dispatching its completions to the right
queue.

* Add the new selectors/types to the XPC allow-list.

* Add NSError to completion for invokeCommands:...

Author: bzbarsky-apple

src/darwin/Framework/CHIP/MTRCommandWithExpectedResult.h

@@ -0,0 +1,61 @@
+/**
+ *    Copyright (c) 2025 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> // For MTRCommandPath
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * An object representing a single command to be invoked and the expected
+ * result of invoking it.
+ */
+MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4))
+@interface MTRCommandWithExpectedResult : NSObject <NSCopying, NSSecureCoding>
+
+/**
+ * The path of the command being invoked.
+ */
+@property (nonatomic, retain) MTRCommandPath * path;
+
+/**
+ * The command fields to pass for the command invoke.  nil if this command does
+ * not have any fields.  If not nil, this should be a data-value dictionary of
+ * MTRStructureValueType.
+ */
+@property (nonatomic, retain, nullable) NSDictionary<NSString *, id> * commandFields;
+
+/**
+ * The expected result of invoking the command.
+ *
+ * If this is nil, that indicates that the invoke is considered successful if it
+ * does not result in an error status response.
+ *
+ * If this is is not nil, then invoke is considered successful if
+ * it results in a data response and for each entry in the provided
+ * expectedResult the field whose field ID matches the key of the entry has a
+ * value that equals the value of the entry.  Values of entries are data-value
+ * dictionaries.
+ */
+@property (nonatomic, copy, nullable) NSDictionary<NSNumber *, NSDictionary<NSString *, id> *> * expectedResult;
+
+- (instancetype)initWithPath:(MTRCommandPath *)path
+               commandFields:(nullable NSDictionary<NSString *, id> *)commandFields
+              expectedResult:(nullable NSDictionary<NSNumber *, NSDictionary<NSString *, id> *> *)expectedResult;
+
+@end
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRCommandWithExpectedResult.mm

@@ -0,0 +1,119 @@
+/**
+ *    Copyright (c) 2025 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 "MTRDeviceDataValidation.h"
+#import "MTRLogging_Internal.h"
+#import <Matter/Matter.h>
+
+@implementation MTRCommandWithExpectedResult
+- (instancetype)initWithPath:(MTRCommandPath *)path
+               commandFields:(nullable NSDictionary<NSString *, id> *)commandFields
+              expectedResult:(nullable NSDictionary<NSNumber *, NSDictionary<NSString *, id> *> *)expectedResult
+{
+    if (self = [super init]) {
+        self.path = path;
+        self.commandFields = commandFields;
+        self.expectedResult = expectedResult;
+    }
+
+    return self;
+}
+
+- (id)copyWithZone:(NSZone *)zone
+{
+    return [[MTRCommandWithExpectedResult alloc] initWithPath:self.path commandFields:self.commandFields expectedResult:self.expectedResult];
+}
+
+- (NSString *)description
+{
+    return [NSString stringWithFormat:@"<%@: %p, path: %@, fields: %@, expectedResult: %@", NSStringFromClass(self.class), self, self.path, self.commandFields, self.expectedResult];
+}
+
+#pragma mark - MTRCommandWithExpectedResult NSSecureCoding implementation
+
+static NSString * const sPathKey = @"pathKey";
+static NSString * const sFieldsKey = @"fieldsKey";
+static NSString * const sExpectedResultKey = @"expectedResultKey";
+
++ (BOOL)supportsSecureCoding
+{
+    return YES;
+}
+
+- (nullable instancetype)initWithCoder:(NSCoder *)decoder
+{
+    self = [super init];
+    if (self == nil) {
+        return nil;
+    }
+
+    _path = [decoder decodeObjectOfClass:MTRCommandPath.class forKey:sPathKey];
+    if (!_path || ![_path isKindOfClass:MTRCommandPath.class]) {
+        MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded %@ for endpoint, not MTRCommandPath.", _path);
+        return nil;
+    }
+
+    _commandFields = [decoder decodeObjectOfClass:NSDictionary.class forKey:sFieldsKey];
+    if (_commandFields) {
+        if (![_commandFields isKindOfClass:NSDictionary.class]) {
+            MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded %@ for commandFields, not NSDictionary.", _commandFields);
+            return nil;
+        }
+
+        if (!MTRDataValueDictionaryIsWellFormed(_commandFields) || ![MTRStructureValueType isEqual:_commandFields[MTRTypeKey]]) {
+            MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded %@ for commandFields, not a structure-typed data-value dictionary.", _commandFields);
+            return nil;
+        }
+    }
+
+    _expectedResult = [decoder decodeObjectOfClass:NSDictionary.class forKey:sExpectedResultKey];
+    if (_expectedResult) {
+        if (![_expectedResult isKindOfClass:NSDictionary.class]) {
+            MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded %@ for expectedResult, not NSDictionary.", _expectedResult);
+            return nil;
+        }
+
+        for (id key in _expectedResult) {
+            if (![key isKindOfClass:NSNumber.class]) {
+                MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded key %@ in expectedResult", key);
+                return nil;
+            }
+
+            if (![_expectedResult[key] isKindOfClass:NSDictionary.class] || !MTRDataValueDictionaryIsWellFormed(_expectedResult[key])) {
+                MTR_LOG_ERROR("MTRCommandWithExpectedResult decoded value %@ for key %@ in expectedResult", _expectedResult[key], key);
+                return nil;
+            }
+        }
+    }
+
+    return self;
+}
+
+- (void)encodeWithCoder:(NSCoder *)coder
+{
+    // In theory path is not nullable, but we don't really enforce that in init.
+    if (self.path) {
+        [coder encodeObject:self.path forKey:sPathKey];
+    }
+    if (self.commandFields) {
+        [coder encodeObject:self.commandFields forKey:sFieldsKey];
+    }
+    if (self.expectedResult) {
+        [coder encodeObject:self.expectedResult forKey:sExpectedResultKey];
+    }
+}
+
+@end

src/darwin/Framework/CHIP/MTRDevice.h

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright (c) 2022-2023 Project CHIP Authors
+ *    Copyright (c) 2022-2025 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.
@@ -19,6 +19,7 @@
 #import <Matter/MTRAttributeValueWaiter.h>
 #import <Matter/MTRBaseClusters.h>
 #import <Matter/MTRBaseDevice.h>
+#import <Matter/MTRCommandWithExpectedResult.h>
 #import <Matter/MTRDefines.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -294,6 +295,31 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
                          completion:(MTRDeviceResponseHandler)completion
     MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
 
+/**
+ * Invoke one or more groups of commands.
+ *
+ * For any given group, if any command in any preceding group failed, the group
+ * will be skipped.  If all commands in all preceding groups succeeded, the
+ * commands within the group will be invoked, with no ordering guarantees within
+ * that group.
+ *
+ * Results from all commands that were invoked will be passed to the provided
+ * completion as an array of response-value dictionaries.  Each of these will
+ * have the command path of the command (see MTRCommandPathKey) and one of three
+ * things:
+ *
+ * 1) No other fields, indicating that the command invoke returned a succcess
+ *    status.
+ * 2) A field for MTRErrorKey, indicating that the invoke returned a failure
+ *    status (which is the value of the field).
+ * 3) A field for MTRDataKey, indicating that the invoke returned a data
+ *    response.  In this case the data-value representing the response will be
+ *    the value of this field.
+ */
+- (void)invokeCommands:(NSArray<NSArray<MTRCommandWithExpectedResult *> *> *)commands
+                 queue:(dispatch_queue_t)queue
+            completion:(MTRDeviceResponseHandler)completion MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4));
+
 /**
  * Open a commissioning window on the device.
  *

src/darwin/Framework/CHIP/MTRDevice.mm

@@ -523,6 +523,16 @@ - (void)_invokeKnownCommandWithEndpointID:(NSNumber *)endpointID
                             completion:responseHandler];
 }
 
+- (void)invokeCommands:(NSArray<NSArray<MTRCommandWithExpectedResult *> *> *)commands
+                 queue:(dispatch_queue_t)queue
+            completion:(MTRDeviceResponseHandler)completion
+{
+    MTR_ABSTRACT_METHOD();
+    dispatch_async(queue, ^{
+        completion(nil, [MTRError errorForCHIPErrorCode:CHIP_ERROR_INCORRECT_STATE]);
+    });
+}
+
 - (void)openCommissioningWindowWithSetupPasscode:(NSNumber *)setupPasscode
                                    discriminator:(NSNumber *)discriminator
                                         duration:(NSNumber *)duration

src/darwin/Framework/CHIP/MTRDeviceController_XPC.mm

@@ -137,14 +137,29 @@ - (NSXPCInterface *)_interfaceForServerProtocol
     NSMutableSet * allowedClasses = [MTRDeviceController_XPC _allowedClasses];
     [allowedClasses addObjectsFromArray:@[
         [MTRCommandPath class],
-        [MTRAttributePath class],
     ]];
 
     [interface setClasses:allowedClasses
               forSelector:@selector(deviceController:nodeID:invokeCommandWithEndpointID:clusterID:commandID:commandFields:expectedValues:expectedValueInterval:timedInvokeTimeout:serverSideProcessingTimeout:completion:)
             argumentIndex:0
                   ofReply:YES];
 
+    // invokeCommands has the same reply types as invokeCommandWithEndpointID.
+    [interface setClasses:allowedClasses
+              forSelector:@selector(deviceController:nodeID:invokeCommands:completion:)
+            argumentIndex:0
+                  ofReply:YES];
+
+    // invokeCommands gets handed MTRCommandWithExpectedResult (which includes
+    // MTRCommandPath, which is already in allowedClasses).
+    [allowedClasses addObjectsFromArray:@[
+        [MTRCommandWithExpectedResult class],
+    ]];
+    [interface setClasses:allowedClasses
+              forSelector:@selector(deviceController:nodeID:invokeCommands:completion:)
+            argumentIndex:2
+                  ofReply:NO];
+
     // readAttributePaths: gets handed an array of MTRAttributeRequestPath.
     allowedClasses = [MTRDeviceController_XPC _allowedClasses];
     [allowedClasses addObjectsFromArray:@[