Remove all mention of "pairing" from non-deprecated Darwin public API…

…s. (project-chip#23647)

This is a re-landing of PR project-chip#22676, but with backwards-compat shims in place.

The change to MTRDeviceControllerDelegate is OK because this is a
newly-introduced protocol.

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

@@ -26,8 +26,7 @@
 @property MTRDeviceController * commissioner;
 @property MTRCommissioningParameters * params;
 
-- (void)onPairingComplete:(NSError *)error;
-- (void)onPairingDeleted:(NSError *)error;
+- (void)onCommissioningSessionEstablishmentDone:(NSError *)error;
 - (void)onCommissioningComplete:(NSError *)error;
 
 @end

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

@@ -44,7 +44,7 @@ - (void)onStatusUpdate:(MTRCommissioningStatus)status
     }
 }
 
-- (void)onPairingComplete:(NSError *)error
+- (void)onCommissioningSessionEstablishmentDone:(NSError *)error
 {
     if (error != nil) {
         ChipLogProgress(chipTool, "PASE establishment failed");
@@ -61,11 +61,6 @@ - (void)onPairingComplete:(NSError *)error
     }
 }
 
-- (void)onPairingDeleted:(NSError *)error
-{
-    _commandBridge->SetCommandExitStatus(error, "Pairing Delete");
-}
-
 - (void)onCommissioningComplete:(NSError *)error
 {
     _commandBridge->SetCommandExitStatus(error, "Pairing Commissioning Complete");

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

@@ -49,8 +49,7 @@ constexpr const char * kDefaultKey = "default";
 @property BOOL active; // Whether to pass on notifications to the commandBridge
 
 - (void)onStatusUpdate:(MTRCommissioningStatus)status;
-- (void)onPairingComplete:(NSError * _Nullable)error;
-- (void)onPairingDeleted:(NSError * _Nullable)error;
+- (void)onCommissioningSessionEstablishmentDone:(NSError * _Nullable)error;
 - (void)onCommissioningComplete:(NSError * _Nullable)error;
 
 - (instancetype)init NS_UNAVAILABLE;
@@ -543,7 +542,7 @@ NS_ASSUME_NONNULL_BEGIN
     }
 }
 
-- (void)onPairingComplete:(NSError * _Nullable)error
+- (void)onCommissioningSessionEstablishmentDone:(NSError * _Nullable)error
 {
     if (_active) {
         if (error != nil) {
@@ -557,13 +556,6 @@ NS_ASSUME_NONNULL_BEGIN
     }
 }
 
-- (void)onPairingDeleted:(NSError * _Nullable)error
-{
-    if (_active) {
-        _commandBridge->PairingDeleted();
-    }
-}
-
 - (void)onCommissioningComplete:(NSError * _Nullable)error
 {
     if (_active) {

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -58,9 +58,9 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
  * provided discriminator.
  *
  * Then a PASE session will be established with the device, unless an error
- * occurs.  MTRDevicePairingDelegate will be notified as follows:
+ * occurs.  MTRDeviceControllerDelegate will be notified as follows:
  *
- * * Discovery fails: onStatusUpdate with MTRPairingStatusFailed.
+ * * Discovery fails: onStatusUpdate with MTRCommissioningStatusFailed.
  *
  * * Discovery succeeds but commissioning session setup fails: onPairingComplete
  *   with an error.
@@ -109,9 +109,9 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
 + (instancetype)new NS_UNAVAILABLE;
 
 /**
- * Set the Delegate for the Device Pairing  as well as the Queue on which the Delegate callbacks will be triggered
+ * Set the Delegate for the device controller  as well as the Queue on which the Delegate callbacks will be triggered
  *
- * @param[in] delegate The delegate the pairing process should use
+ * @param[in] delegate The delegate the commissioning process should use
  *
  * @param[in] queue The queue on which the callbacks will be delivered
  */

src/darwin/Framework/CHIP/MTRDeviceController.mm

@@ -850,18 +850,14 @@ - (BOOL)respondsToSelector:(SEL)selector
         return [self.delegate respondsToSelector:@selector(onStatusUpdate:)];
     }
 
-    if (selector == @selector(onPairingComplete:)) {
+    if (selector == @selector(onCommissioningSessionEstablishmentDone:)) {
         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];
 }
 
@@ -870,7 +866,7 @@ - (void)onStatusUpdate:(MTRCommissioningStatus)status
     [self.delegate onStatusUpdate:static_cast<MTRPairingStatus>(status)];
 }
 
-- (void)onPairingComplete:(NSError * _Nullable)error
+- (void)onCommissioningSessionEstablishmentDone:(NSError * _Nullable)error
 {
     [self.delegate onPairingComplete:error];
 }

src/darwin/Framework/CHIP/MTRDeviceControllerDelegate.h

@@ -27,37 +27,29 @@ typedef NS_ENUM(NSInteger, MTRCommissioningStatus) {
 } MTR_NEWLY_AVAILABLE;
 
 /**
- * The protocol definition for the MTRDeviceControllerDelegate
+ * The protocol definition for the MTRDeviceControllerDelegate.
  *
  * All delegate methods will be called on the supplied Delegate Queue.
  */
 MTR_NEWLY_AVAILABLE
 @protocol MTRDeviceControllerDelegate <NSObject>
 @optional
 /**
- * Notify the delegate when pairing status gets updated
- *
+ * Notify the delegate when commissioning status gets updated.
  */
 - (void)onStatusUpdate:(MTRCommissioningStatus)status;
 
 /**
- * Notify the delegate when pairing is completed
- *
+ * Notify the delegate when a commissioning session is established or the
+ * establishment has errored out.
  */
-- (void)onPairingComplete:(NSError * _Nullable)error;
+- (void)onCommissioningSessionEstablishmentDone:(NSError * _Nullable)error;
 
 /**
- * Notify the delegate when commissioning is completed
- *
+ * Notify the delegate when commissioning is completed.
  */
 - (void)onCommissioningComplete:(NSError * _Nullable)error;
 
-/**
- * Notify the delegate when pairing is deleted
- *
- */
-- (void)onPairingDeleted:(NSError * _Nullable)error;
-
 @end
 
 typedef NS_ENUM(NSUInteger, MTRPairingStatus) {

src/darwin/Framework/CHIP/MTRDeviceControllerDelegateBridge.mm

@@ -73,11 +73,11 @@
     NSLog(@"DeviceControllerDelegate Pairing complete. Status %s", chip::ErrorStr(error));
 
     id<MTRDeviceControllerDelegate> strongDelegate = mDelegate;
-    if ([strongDelegate respondsToSelector:@selector(onPairingComplete:)]) {
+    if ([strongDelegate respondsToSelector:@selector(onCommissioningSessionEstablishmentDone:)]) {
         if (strongDelegate && mQueue) {
             dispatch_async(mQueue, ^{
                 NSError * nsError = [MTRError errorForCHIPErrorCode:error];
-                [strongDelegate onPairingComplete:nsError];
+                [strongDelegate onCommissioningSessionEstablishmentDone:nsError];
             });
         }
     }
@@ -87,15 +87,7 @@
 {
     NSLog(@"DeviceControllerDelegate Pairing deleted. Status %s", chip::ErrorStr(error));
 
-    id<MTRDeviceControllerDelegate> strongDelegate = mDelegate;
-    if ([strongDelegate respondsToSelector:@selector(onPairingDeleted:)]) {
-        if (strongDelegate && mQueue) {
-            dispatch_async(mQueue, ^{
-                NSError * nsError = [MTRError errorForCHIPErrorCode:error];
-                [strongDelegate onPairingDeleted:nsError];
-            });
-        }
-    }
+    // This is never actually called; just do nothing.
 }
 
 void MTRDeviceControllerDelegateBridge::OnCommissioningComplete(chip::NodeId nodeId, CHIP_ERROR error)

src/darwin/Framework/CHIP/MTRSetupPayload.h

@@ -20,7 +20,7 @@
 NS_ASSUME_NONNULL_BEGIN
 
 typedef NS_OPTIONS(NSUInteger, MTRDiscoveryCapabilities) {
-    MTRDiscoveryCapabilitiesUnknown = 0, // Device capabilities are not known (e.g. all we have is a manual pairing code).
+    MTRDiscoveryCapabilitiesUnknown = 0, // Device capabilities are not known (e.g. all we have is a numeric code).
     MTRDiscoveryCapabilitiesNone MTR_NEWLY_DEPRECATED("Please use MTRDiscoveryCapabilitiesUnknown") = 0,
     MTRDiscoveryCapabilitiesSoftAP = 1 << 0, // Device supports WiFi softAP
     MTRDiscoveryCapabilitiesBLE = 1 << 1, // Device supports BLE
@@ -31,8 +31,8 @@ typedef NS_OPTIONS(NSUInteger, MTRDiscoveryCapabilities) {
 };
 
 typedef NS_ENUM(NSUInteger, MTRCommissioningFlow) {
-    MTRCommissioningFlowStandard = 0, // Device automatically enters pairing mode upon power-up
-    MTRCommissioningFlowUserActionRequired = 1, // Device requires a user interaction to enter pairing mode
+    MTRCommissioningFlowStandard = 0, // Device automatically enters commissioning mode upon power-up
+    MTRCommissioningFlowUserActionRequired = 1, // Device requires a user interaction to enter commissioning mode
     MTRCommissioningFlowCustom = 2, // Commissioning steps should be retrieved from the distributed compliance ledger
     MTRCommissioningFlowInvalid = 3,
 };
@@ -58,8 +58,10 @@ typedef NS_ENUM(NSUInteger, MTROptionalQRCodeInfoType) {
 @end
 
 /**
- * A setup payload that can be created from a pairing code and serialized to a
- * pairing code.
+ * A setup payload that can be created from a numeric code or QR code and
+ * serialized to a numeric code or QR code, though serializing to QR code after
+ * creating from numeric code will not work, because some required information
+ * will be missing.
  */
 @interface MTRSetupPayload : NSObject <NSSecureCoding>
 

src/darwin/Framework/CHIPTests/MTRDeviceTests.m

@@ -94,7 +94,7 @@ - (id)initWithExpectation:(XCTestExpectation *)expectation
     return self;
 }
 
-- (void)onPairingComplete:(NSError *)error
+- (void)onCommissioningSessionEstablishmentDone:(NSError *)error
 {
     XCTAssertEqual(error.code, 0);
 

src/darwin/Framework/CHIPTests/MTRXPCListenerSampleTests.m

@@ -419,7 +419,7 @@ - (id)initWithExpectation:(XCTestExpectation *)expectation
     return self;
 }
 
-- (void)onPairingComplete:(NSError *)error
+- (void)onCommissioningSessionEstablishmentDone:(NSError *)error
 {
     XCTAssertEqual(error.code, 0);
     NSError * commissionError = nil;