[Darwin] Rename MTRDevicePairingDelegate to MTRDeviceControllerDelegate and MTRPairingStatus to MTRCommissioningStatus (#23587)

* [Darwin] Rename MTRDevicePairingDelegate to MTRDeviceControllerDelegate and MTRPairingStatus to MTRCommissioningStatus

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

* [Darwin] Rename MTRDevicePairingDelegate to MTRDeviceControllerDelegate

* [Darwin] Rename MTRPairingStatus to MTRCommissioningStatus

* Add backwards compat shims for the old APIs.

* Address review comments.

Co-authored-by: Vivien Nicolas <vnicolas@apple.com>

Author: 2 people

examples/darwin-framework-tool/BUILD.gn

@@ -128,10 +128,10 @@ executable("darwin-framework-tool") {
     "commands/common/MTRError_Utils.h",
     "commands/common/MTRLogging.h",
     "commands/pairing/Commands.h",
+    "commands/pairing/DeviceControllerDelegateBridge.mm",
     "commands/pairing/OpenCommissioningWindowCommand.h",
     "commands/pairing/OpenCommissioningWindowCommand.mm",
     "commands/pairing/PairingCommandBridge.mm",
-    "commands/pairing/PairingDelegateBridge.mm",
     "commands/payload/SetupPayloadParseCommand.mm",
     "commands/provider/Commands.h",
     "commands/provider/OTAProviderDelegate.mm",

examples/darwin-framework-tool/commands/pairing/PairingDelegateBridge.h examples/darwin-framework-tool/commands/pairing/DeviceControllerDelegateBridge.h

@@ -20,7 +20,7 @@
 
 #import <Matter/Matter.h>
 
-@interface CHIPToolPairingDelegate : NSObject <MTRDevicePairingDelegate>
+@interface CHIPToolDeviceControllerDelegate : NSObject <MTRDeviceControllerDelegate>
 @property PairingCommandBridge * commandBridge;
 @property chip::NodeId deviceID;
 @property MTRDeviceController * commissioner;

examples/darwin-framework-tool/commands/pairing/PairingDelegateBridge.mm examples/darwin-framework-tool/commands/pairing/DeviceControllerDelegateBridge.mm

@@ -16,29 +16,29 @@
  *
  */
 
-#include "PairingDelegateBridge.h"
+#include "DeviceControllerDelegateBridge.h"
 #import <Matter/Matter.h>
 
-@interface CHIPToolPairingDelegate ()
+@interface CHIPToolDeviceControllerDelegate ()
 @end
 
-@implementation CHIPToolPairingDelegate
-- (void)onStatusUpdate:(MTRPairingStatus)status
+@implementation CHIPToolDeviceControllerDelegate
+- (void)onStatusUpdate:(MTRCommissioningStatus)status
 {
     NSLog(@"Pairing Status Update: %tu", status);
     switch (status) {
-    case MTRPairingStatusSuccess:
+    case MTRCommissioningStatusSuccess:
         ChipLogProgress(chipTool, "Secure Pairing Success");
         ChipLogProgress(chipTool, "CASE establishment successful");
         break;
-    case MTRPairingStatusFailed:
+    case MTRCommissioningStatusFailed:
         ChipLogError(chipTool, "Secure Pairing Failed");
         _commandBridge->SetCommandExitStatus(CHIP_ERROR_INCORRECT_STATE);
         break;
-    case MTRPairingStatusDiscoveringMoreDevices:
+    case MTRCommissioningStatusDiscoveringMoreDevices:
         ChipLogProgress(chipTool, "Secure Pairing Discovering More Devices");
         break;
-    case MTRPairingStatusUnknown:
+    case MTRCommissioningStatusUnknown:
         ChipLogError(chipTool, "Uknown Pairing Status");
         break;
     }

examples/darwin-framework-tool/commands/pairing/PairingCommandBridge.h

@@ -78,7 +78,7 @@ class PairingCommandBridge : public CHIPCommandBridge
     void PairWithCode(NSError * __autoreleasing * error);
     void PairWithPayload(NSError * __autoreleasing * error);
     void Unpair();
-    void SetUpPairingDelegate();
+    void SetUpDeviceControllerDelegate();
 
     const PairingMode mPairingMode;
     const PairingNetworkType mNetworkType;

examples/darwin-framework-tool/commands/pairing/PairingCommandBridge.mm

@@ -19,23 +19,23 @@
 #import <Matter/Matter.h>
 
 #include "../common/CHIPCommandBridge.h"
+#include "DeviceControllerDelegateBridge.h"
 #include "PairingCommandBridge.h"
-#include "PairingDelegateBridge.h"
 #include <lib/support/logging/CHIPLogging.h>
 
 #import "MTRError_Utils.h"
 
 using namespace ::chip;
 using namespace ::chip::Controller;
 
-void PairingCommandBridge::SetUpPairingDelegate()
+void PairingCommandBridge::SetUpDeviceControllerDelegate()
 {
     dispatch_queue_t callbackQueue = dispatch_queue_create("com.chip.pairing", DISPATCH_QUEUE_SERIAL);
-    CHIPToolPairingDelegate * pairing = [[CHIPToolPairingDelegate alloc] init];
+    CHIPToolDeviceControllerDelegate * deviceControllerDelegate = [[CHIPToolDeviceControllerDelegate alloc] init];
     MTRCommissioningParameters * params = [[MTRCommissioningParameters alloc] init];
     MTRDeviceController * commissioner = CurrentCommissioner();
 
-    [pairing setDeviceID:mNodeId];
+    [deviceControllerDelegate setDeviceID:mNodeId];
     switch (mNetworkType) {
     case PairingNetworkType::None:
     case PairingNetworkType::Ethernet:
@@ -49,11 +49,11 @@
         break;
     }
 
-    [pairing setCommandBridge:this];
-    [pairing setParams:params];
-    [pairing setCommissioner:commissioner];
+    [deviceControllerDelegate setCommandBridge:this];
+    [deviceControllerDelegate setParams:params];
+    [deviceControllerDelegate setCommissioner:commissioner];
 
-    [commissioner setPairingDelegate:pairing queue:callbackQueue];
+    [commissioner setDeviceControllerDelegate:deviceControllerDelegate queue:callbackQueue];
 }
 
 CHIP_ERROR PairingCommandBridge::RunCommand()
@@ -79,7 +79,7 @@
 
 void PairingCommandBridge::PairWithCode(NSError * __autoreleasing * error)
 {
-    SetUpPairingDelegate();
+    SetUpDeviceControllerDelegate();
     auto * payload = [[MTRSetupPayload alloc] initWithSetupPasscode:@(mSetupPINCode) discriminator:@(mDiscriminator)];
     MTRDeviceController * commissioner = CurrentCommissioner();
     [commissioner setupCommissioningSessionWithPayload:payload newNodeID:@(mNodeId) error:error];
@@ -88,7 +88,7 @@
 void PairingCommandBridge::PairWithPayload(NSError * __autoreleasing * error)
 {
     NSString * onboardingPayload = [NSString stringWithUTF8String:mOnboardingPayload];
-    SetUpPairingDelegate();
+    SetUpDeviceControllerDelegate();
     auto * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:onboardingPayload error:error];
     if (payload == nil) {
         return;

examples/darwin-framework-tool/commands/tests/TestCommandBridge.h

@@ -43,12 +43,12 @@ const char * getScriptsFolder() { return basePath; }
 
 constexpr const char * kDefaultKey = "default";
 
-@interface TestPairingDelegate : NSObject <MTRDevicePairingDelegate>
+@interface TestDeviceControllerDelegate : NSObject <MTRDeviceControllerDelegate>
 @property TestCommandBridge * commandBridge;
 @property chip::NodeId deviceId;
 @property BOOL active; // Whether to pass on notifications to the commandBridge
 
-- (void)onStatusUpdate:(MTRPairingStatus)status;
+- (void)onStatusUpdate:(MTRCommissioningStatus)status;
 - (void)onPairingComplete:(NSError * _Nullable)error;
 - (void)onPairingDeleted:(NSError * _Nullable)error;
 - (void)onCommissioningComplete:(NSError * _Nullable)error;
@@ -70,7 +70,7 @@ class TestCommandBridge : public CHIPCommandBridge,
 public:
     TestCommandBridge(const char * _Nonnull commandName)
         : CHIPCommandBridge(commandName)
-        , mPairingDelegate([[TestPairingDelegate alloc] initWithTestCommandBridge:this])
+        , mDeviceControllerDelegate([[TestDeviceControllerDelegate alloc] initWithTestCommandBridge:this])
     {
         AddArgument("delayInMs", 0, UINT64_MAX, &mDelayInMs);
         AddArgument("PICS", &mPICSFilePath);
@@ -183,9 +183,9 @@ class TestCommandBridge : public CHIPCommandBridge,
 
         SetIdentity(identity);
 
-        [controller setPairingDelegate:mPairingDelegate queue:mCallbackQueue];
-        [mPairingDelegate setDeviceId:value.nodeId];
-        [mPairingDelegate setActive:YES];
+        [controller setDeviceControllerDelegate:mDeviceControllerDelegate queue:mCallbackQueue];
+        [mDeviceControllerDelegate setDeviceId:value.nodeId];
+        [mDeviceControllerDelegate setActive:YES];
 
         NSString * payloadStr = [[NSString alloc] initWithBytes:value.payload.data()
                                                          length:value.payload.size()
@@ -521,21 +521,21 @@ class TestCommandBridge : public CHIPCommandBridge,
     }
 
 private:
-    TestPairingDelegate * _Nonnull mPairingDelegate;
+    TestDeviceControllerDelegate * _Nonnull mDeviceControllerDelegate;
 
     // Set of our connected devices, keyed by identity.
     std::map<std::string, MTRBaseDevice *> mConnectedDevices;
 };
 
 NS_ASSUME_NONNULL_BEGIN
 
-@implementation TestPairingDelegate
-- (void)onStatusUpdate:(MTRPairingStatus)status
+@implementation TestDeviceControllerDelegate
+- (void)onStatusUpdate:(MTRCommissioningStatus)status
 {
     if (_active) {
-        if (status == MTRPairingStatusSuccess) {
+        if (status == MTRCommissioningStatusSuccess) {
             NSLog(@"Secure pairing success");
-        } else if (status == MTRPairingStatusFailed) {
+        } else if (status == MTRCommissioningStatusFailed) {
             _active = NO;
             NSLog(@"Secure pairing failed");
             _commandBridge->OnStatusUpdate(chip::app::StatusIB(chip::Protocols::InteractionModel::Status::Failure));

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -29,6 +29,7 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
 @class MTRCommissioningParameters;
 @class MTRSetupPayload;
 @protocol MTRDevicePairingDelegate;
+@protocol MTRDeviceControllerDelegate;
 
 @interface MTRDeviceController : NSObject
 
@@ -114,7 +115,7 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
  *
  * @param[in] queue The queue on which the callbacks will be delivered
  */
-- (void)setPairingDelegate:(id<MTRDevicePairingDelegate>)delegate queue:(dispatch_queue_t)queue;
+- (void)setDeviceControllerDelegate:(id<MTRDeviceControllerDelegate>)delegate queue:(dispatch_queue_t)queue MTR_NEWLY_AVAILABLE;
 
 /**
  * Sets this MTRDeviceController to use the given issuer for issuing operational certs. By default, the MTRDeviceController uses an
@@ -217,6 +218,9 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
                                     salt:(NSData *)salt
     MTR_NEWLY_DEPRECATED("Please use computePASEVerifierForSetupPasscode:iterations:salt:error:");
 
+- (void)setPairingDelegate:(id<MTRDevicePairingDelegate>)delegate
+                     queue:(dispatch_queue_t)queue MTR_NEWLY_DEPRECATED("Please use setDeviceControllerDelegate:");
+
 @end
 
 NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRDeviceController.mm

@@ -20,10 +20,10 @@
 
 #import "MTRBaseDevice_Internal.h"
 #import "MTRCommissioningParameters.h"
+#import "MTRDeviceControllerDelegateBridge.h"
 #import "MTRDeviceControllerFactory_Internal.h"
 #import "MTRDeviceControllerStartupParams.h"
 #import "MTRDeviceControllerStartupParams_Internal.h"
-#import "MTRDevicePairingDelegateBridge.h"
 #import "MTRDevice_Internal.h"
 #import "MTRError_Internal.h"
 #import "MTRKeypair.h"
@@ -84,7 +84,7 @@ @interface MTRDeviceController ()
 
 @property (readonly) chip::Controller::DeviceCommissioner * cppCommissioner;
 @property (readonly) chip::Credentials::PartialDACVerifier * partialDACVerifier;
-@property (readonly) MTRDevicePairingDelegateBridge * pairingDelegateBridge;
+@property (readonly) MTRDeviceControllerDelegateBridge * deviceControllerDelegateBridge;
 @property (readonly) MTROperationalCredentialsDelegate * operationalCredentialsDelegate;
 @property (readonly) MTRP256KeypairBridge signingKeypairBridge;
 @property (readonly) MTRP256KeypairBridge operationalKeypairBridge;
@@ -104,8 +104,8 @@ - (instancetype)initWithFactory:(MTRDeviceControllerFactory *)factory queue:(dis
         _deviceMapLock = OS_UNFAIR_LOCK_INIT;
         _nodeIDToDeviceMap = [NSMutableDictionary dictionary];
 
-        _pairingDelegateBridge = new MTRDevicePairingDelegateBridge();
-        if ([self checkForInitError:(_pairingDelegateBridge != nullptr) logMsg:kErrorPairingInit]) {
+        _deviceControllerDelegateBridge = new MTRDeviceControllerDelegateBridge();
+        if ([self checkForInitError:(_deviceControllerDelegateBridge != nullptr) logMsg:kErrorPairingInit]) {
             return nil;
         }
 
@@ -184,9 +184,9 @@ - (void)cleanup
         _partialDACVerifier = nullptr;
     }
 
-    if (_pairingDelegateBridge) {
-        delete _pairingDelegateBridge;
-        _pairingDelegateBridge = nullptr;
+    if (_deviceControllerDelegateBridge) {
+        delete _deviceControllerDelegateBridge;
+        _deviceControllerDelegateBridge = nullptr;
     }
 }
 
@@ -256,7 +256,7 @@ - (BOOL)startup:(MTRDeviceControllerStartupParamsInternal *)startupParams
 
         chip::Controller::SetupParams commissionerParams;
 
-        commissionerParams.pairingDelegate = _pairingDelegateBridge;
+        commissionerParams.pairingDelegate = _deviceControllerDelegateBridge;
 
         _operationalCredentialsDelegate->SetDeviceCommissioner(_cppCommissioner);
 
@@ -535,14 +535,14 @@ - (void)removeDevice:(MTRDevice *)device
     os_unfair_lock_unlock(&_deviceMapLock);
 }
 
-- (void)setPairingDelegate:(id<MTRDevicePairingDelegate>)delegate queue:(dispatch_queue_t)queue
+- (void)setDeviceControllerDelegate:(id<MTRDeviceControllerDelegate>)delegate queue:(dispatch_queue_t)queue
 {
     VerifyOrReturn([self checkIsRunning]);
 
     dispatch_async(_chipWorkQueue, ^{
         VerifyOrReturn([self checkIsRunning]);
 
-        self->_pairingDelegateBridge->setDelegate(delegate, queue);
+        self->_deviceControllerDelegateBridge->setDelegate(delegate, queue);
     });
 }
 
@@ -823,6 +823,70 @@ - (void)invalidateCASESessionForNode:(chip::NodeId)nodeID;
 }
 @end
 
+/**
+ * Shim to allow us to treat an MTRDevicePairingDelegate as an
+ * MTRDeviceControllerDelegate.
+ */
+@interface MTRDevicePairingDelegateShim : NSObject <MTRDeviceControllerDelegate>
+@property (nonatomic, readonly) id<MTRDevicePairingDelegate> delegate;
+- (instancetype)initWithDelegate:(id<MTRDevicePairingDelegate>)delegate;
+@end
+
+@implementation MTRDevicePairingDelegateShim
+- (instancetype)initWithDelegate:(id<MTRDevicePairingDelegate>)delegate
+{
+    if (self = [super init]) {
+        _delegate = delegate;
+    }
+    return self;
+}
+
+- (BOOL)respondsToSelector:(SEL)selector
+{
+    // This logic will need to change a bit when the MTRDeviceControllerDelegate
+    // signatures change.  It's shaped the way it is to make those changes
+    // easier.
+    if (selector == @selector(onStatusUpdate:)) {
+        return [self.delegate respondsToSelector:@selector(onStatusUpdate:)];
+    }
+
+    if (selector == @selector(onPairingComplete:)) {
+        return [self.delegate respondsToSelector:@selector(onPairingComplete:)];
+    }
+
+    if (selector == @selector(onCommissioningComplete:)) {
+        return [self.delegate respondsToSelector:@selector(onCommissioningComplete:)];
+    }
+
+    if (selector == @selector(onPairingDeleted:)) {
+        return [self.delegate respondsToSelector:@selector(onPairingDeleted:)];
+    }
+
+    return [super respondsToSelector:selector];
+}
+
+- (void)onStatusUpdate:(MTRCommissioningStatus)status
+{
+    [self.delegate onStatusUpdate:static_cast<MTRPairingStatus>(status)];
+}
+
+- (void)onPairingComplete:(NSError * _Nullable)error
+{
+    [self.delegate onPairingComplete:error];
+}
+
+- (void)onCommissioningComplete:(NSError * _Nullable)error
+{
+    [self.delegate onCommissioningComplete:error];
+}
+
+- (void)onPairingDeleted:(NSError * _Nullable)error
+{
+    [self.delegate onPairingDeleted:error];
+}
+
+@end
+
 @implementation MTRDeviceController (Deprecated)
 
 - (NSNumber *)controllerNodeId
@@ -1040,4 +1104,10 @@ - (nullable NSData *)computePaseVerifier:(uint32_t)setupPincode iterations:(uint
     return [MTRDeviceController computePASEVerifierForSetupPasscode:@(setupPincode) iterations:@(iterations) salt:salt error:nil];
 }
 
+- (void)setPairingDelegate:(id<MTRDevicePairingDelegate>)delegate queue:(dispatch_queue_t)queue
+{
+    auto * delegateShim = [[MTRDevicePairingDelegateShim alloc] initWithDelegate:delegate];
+    [self setDeviceControllerDelegate:delegateShim queue:queue];
+}
+
 @end