Darwin API review fixes for MTRSetupPayload and MTROptionalQRCodeInfo (#22566)

* Rename MTRDiscoveryCapabilitiesNone to MTRDiscoveryCapabilitiesUnknown to
  indicate capabilities unknown (e.g. manual setup code).
* In MTROptionalQRCodeInfo mark integerValue and stringValue as nullable and
  document they are mutually exclusive.
* In MTROptionalQRCodeInfo switch infoType to MTROptionalQRCodeInfoType, not
  NSNumber.
* Change rendezvousInformation to just be a MTRDiscoveryCapabilities value, not
  nullable NSNumber, with MTRDiscoveryCapabilitiesNone meaning unknown. When
  parsing QR code, if the value ends up as 0, reset it to
  MTRDiscoveryCapabilitiesOnNetwork.
* Rename setUpPINCode to setupPasscode.
* Mark serialNumber as nullable.
* Add setupPayloadWithOnboardingPayload class method on MTRSetupPayload.
* Stop exposing the various payload parser APIs from the framework;
  consumers should use setupPayloadWithOnboardingPayload.

Fixes #22543

Fixes #22539

Addresses part of #22420

Author: bzbarsky-apple

examples/darwin-framework-tool/commands/payload/SetupPayloadParseCommand.mm

@@ -61,7 +61,7 @@
     NSString * codeString = [NSString stringWithCString:mCode encoding:NSASCIIStringEncoding];
     NSError * error;
     MTRSetupPayload * payload;
-    payload = [MTROnboardingPayloadParser setupPayloadForOnboardingPayload:codeString error:&error];
+    payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:codeString error:&error];
     if (error) {
         LogNSError("Error: ", error);
         return CHIP_ERROR_INTERNAL;
@@ -78,37 +78,33 @@
     NSLog(@"ProductID:     %@", payload.productID);
     NSLog(@"Custom flow:   %lu    (%@)", payload.commissioningFlow, CustomFlowString(payload.commissioningFlow));
     {
-        if (payload.rendezvousInformation == nil) {
+        if (payload.discoveryCapabilities == MTRDiscoveryCapabilitiesUnknown) {
             NSLog(@"Capabilities:  UNKNOWN");
         } else {
             NSMutableString * humanFlags = [[NSMutableString alloc] init];
 
-            auto value = [payload.rendezvousInformation unsignedLongValue];
-            if (value == MTRDiscoveryCapabilitiesNone) {
-                [humanFlags appendString:@"NONE"];
-            } else {
-                if (value & MTRDiscoveryCapabilitiesSoftAP) {
-                    [humanFlags appendString:@"SoftAP"];
-                }
-                if (value & MTRDiscoveryCapabilitiesBLE) {
-                    if (!humanFlags) {
-                        [humanFlags appendString:@", "];
-                    }
-                    [humanFlags appendString:@"BLE"];
+            auto value = payload.discoveryCapabilities;
+            if (value & MTRDiscoveryCapabilitiesSoftAP) {
+                [humanFlags appendString:@"SoftAP"];
+            }
+            if (value & MTRDiscoveryCapabilitiesBLE) {
+                if (!humanFlags) {
+                    [humanFlags appendString:@", "];
                 }
-                if (value & MTRDiscoveryCapabilitiesOnNetwork) {
-                    if (!humanFlags) {
-                        [humanFlags appendString:@", "];
-                    }
-                    [humanFlags appendString:@"ON NETWORK"];
+                [humanFlags appendString:@"BLE"];
+            }
+            if (value & MTRDiscoveryCapabilitiesOnNetwork) {
+                if (!humanFlags) {
+                    [humanFlags appendString:@", "];
                 }
+                [humanFlags appendString:@"ON NETWORK"];
             }
 
             NSLog(@"Capabilities:  0x%02lX (%@)", value, humanFlags);
         }
     }
     NSLog(@"Discriminator: %@", payload.discriminator);
-    NSLog(@"Passcode:      %@", payload.setUpPINCode);
+    NSLog(@"Passcode:      %@", payload.setupPasscode);
 
     if (payload.serialNumber) {
         NSLog(@"SerialNumber: %@", payload.serialNumber);
@@ -120,8 +116,8 @@
         return CHIP_ERROR_INTERNAL;
     }
     for (const MTROptionalQRCodeInfo * info : optionalVendorData) {
-        bool isTypeString = [info.infoType isEqual:@(MTROptionalQRCodeInfoTypeString)];
-        bool isTypeInt32 = [info.infoType isEqual:@(MTROptionalQRCodeInfoTypeInt32)];
+        bool isTypeString = (info.infoType == MTROptionalQRCodeInfoTypeString);
+        bool isTypeInt32 = (info.infoType == MTROptionalQRCodeInfoTypeInt32);
         VerifyOrReturnError(isTypeString || isTypeInt32, CHIP_ERROR_INVALID_ARGUMENT);
 
         if (isTypeString) {

src/darwin/CHIPTool/CHIPTool/View Controllers/Enumeration/EnumerateViewController.m

@@ -133,7 +133,7 @@ - (void)enumerate
             for (NSNumber * endpoint in endpointsInUse) {
                 MTRBaseClusterDescriptor * descriptorCluster =
                     [[MTRBaseClusterDescriptor alloc] initWithDevice:device endpoint:endpoint queue:dispatch_get_main_queue()];
-                [descriptorCluster readAttributeDeviceListWithCompletionHandler:^(
+                [descriptorCluster readAttributeDeviceTypeListWithCompletionHandler:^(
                     NSArray * _Nullable value, NSError * _Nullable error) {
                     if (error) {
                         NSString * resultLog = [[NSString alloc]

src/darwin/CHIPTool/CHIPTool/View Controllers/QRCode/QRCodeViewController.m

@@ -706,10 +706,10 @@ - (void)updateUIFields:(MTRSetupPayload *)payload rawPayload:(nullable NSString
     } else {
         _manualCodeLabel.hidden = YES;
         _versionLabel.text = [NSString stringWithFormat:@"%@", payload.version];
-        if (payload.rendezvousInformation == nil) {
+        if (payload.discoveryCapabilities == MTRDiscoveryCapabilitiesUnknown) {
             _rendezVousInformation.text = NOT_APPLICABLE_STRING;
         } else {
-            _rendezVousInformation.text = [NSString stringWithFormat:@"%lu", [payload.rendezvousInformation unsignedLongValue]];
+            _rendezVousInformation.text = [NSString stringWithFormat:@"%lu", payload.discoveryCapabilities];
         }
         if ([payload.serialNumber length] > 0) {
             self->_serialNumber.text = payload.serialNumber;
@@ -719,7 +719,7 @@ - (void)updateUIFields:(MTRSetupPayload *)payload rawPayload:(nullable NSString
     }
 
     _discriminatorLabel.text = [NSString stringWithFormat:@"%@", payload.discriminator];
-    _setupPinCodeLabel.text = [NSString stringWithFormat:@"%@", payload.setUpPINCode];
+    _setupPinCodeLabel.text = [NSString stringWithFormat:@"%@", payload.setupPasscode];
     // TODO: Only display vid and pid if present
     _vendorID.text = [NSString stringWithFormat:@"%@", payload.vendorID];
     _productID.text = [NSString stringWithFormat:@"%@", payload.productID];
@@ -747,7 +747,7 @@ - (void)parseOptionalData:(MTRSetupPayload *)payload
             continue;
         }
 
-        BOOL isTypeString = [info.infoType isEqualToNumber:[NSNumber numberWithInt:MTROptionalQRCodeInfoTypeString]];
+        BOOL isTypeString = (info.infoType == MTROptionalQRCodeInfoTypeString);
         if (!isTypeString) {
             return;
         }
@@ -767,26 +767,29 @@ - (void)parseOptionalData:(MTRSetupPayload *)payload
 
 - (void)handleRendezVous:(MTRSetupPayload *)payload rawPayload:(NSString *)rawPayload
 {
-    if (payload.rendezvousInformation == nil) {
+    if (payload.discoveryCapabilities == MTRDiscoveryCapabilitiesUnknown) {
         NSLog(@"Rendezvous Default");
         [self handleRendezVousDefault:rawPayload];
         return;
     }
 
-    // TODO: This is a pretty broken way to handle a bitmask.
-    switch ([payload.rendezvousInformation unsignedLongValue]) {
-    case MTRDiscoveryCapabilitiesNone:
-    case MTRDiscoveryCapabilitiesOnNetwork:
-    case MTRDiscoveryCapabilitiesBLE:
-    case MTRDiscoveryCapabilitiesAllMask:
+    // Avoid SoftAP if we have other options.
+    if ((payload.discoveryCapabilities & MTRDiscoveryCapabilitiesOnNetwork)
+        || (payload.discoveryCapabilities & MTRDiscoveryCapabilitiesBLE)) {
         NSLog(@"Rendezvous Default");
         [self handleRendezVousDefault:rawPayload];
-        break;
-    case MTRDiscoveryCapabilitiesSoftAP:
+        return;
+    }
+
+    if (payload.discoveryCapabilities & MTRDiscoveryCapabilitiesSoftAP) {
         NSLog(@"Rendezvous Wi-Fi");
         [self handleRendezVousWiFi:[self getNetworkName:payload.discriminator]];
-        break;
+        return;
     }
+
+    // Just fall back on the default.
+    NSLog(@"Rendezvous Default");
+    [self handleRendezVousDefault:rawPayload];
 }
 
 - (NSString *)getNetworkName:(NSNumber *)discriminator
@@ -879,9 +882,8 @@ - (void)scannedQRCode:(NSString *)qrCode
         [self->_captureSession stopRunning];
         [self->_session invalidateSession];
     });
-    MTRQRCodeSetupPayloadParser * parser = [[MTRQRCodeSetupPayloadParser alloc] initWithBase38Representation:qrCode];
     NSError * error;
-    _setupPayload = [parser populatePayload:&error];
+    _setupPayload = [MTRSetupPayload setupPayloadWithOnboardingPayload:qrCode error:&error];
     dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 1.0 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{
         [self postScanningQRCodeState];
 
@@ -952,9 +954,8 @@ - (IBAction)enteredManualCode:(id)sender
     NSString * decimalString = _manualCodeTextField.text;
     [self manualCodeEnteredStartState];
 
-    MTRManualSetupPayloadParser * parser = [[MTRManualSetupPayloadParser alloc] initWithDecimalStringRepresentation:decimalString];
     NSError * error;
-    _setupPayload = [parser populatePayload:&error];
+    _setupPayload = [MTRSetupPayload setupPayloadWithOnboardingPayload:decimalString error:&error];
     dispatch_after(dispatch_time(DISPATCH_TIME_NOW, INDICATOR_DELAY), dispatch_get_main_queue(), ^{
         [self displayManualCodeInSetupPayloadView:self->_setupPayload decimalString:decimalString withError:error];
     });

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -18,7 +18,6 @@
 #import <Foundation/Foundation.h>
 
 #import <Matter/MTRNOCChainIssuer.h>
-#import <Matter/MTROnboardingPayloadParser.h>
 
 @class MTRBaseDevice;
 

src/darwin/Framework/CHIP/MTRSetupPayload.h

@@ -19,8 +19,8 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-typedef NS_ENUM(NSUInteger, MTRDiscoveryCapabilities) {
-    MTRDiscoveryCapabilitiesNone = 0, // Device does not support any method for rendezvous
+typedef NS_OPTIONS(NSUInteger, MTRDiscoveryCapabilities) {
+    MTRDiscoveryCapabilitiesUnknown = 0, // Device capabilties are not known (e.g. all we have is a manual pairing code).
     MTRDiscoveryCapabilitiesSoftAP = 1 << 0, // Device supports WiFi softAP
     MTRDiscoveryCapabilitiesBLE = 1 << 1, // Device supports BLE
     MTRDiscoveryCapabilitiesOnNetwork = 1 << 2, // Device supports On Network setup
@@ -36,44 +36,62 @@ typedef NS_ENUM(NSUInteger, MTRCommissioningFlow) {
     MTRCommissioningFlowInvalid = 3,
 };
 
-typedef NS_ENUM(NSUInteger, MTROptionalQRCodeInfoType) {
-    MTROptionalQRCodeInfoTypeUnknown,
-    MTROptionalQRCodeInfoTypeString,
-    MTROptionalQRCodeInfoTypeInt32
-};
+typedef NS_ENUM(NSUInteger, MTROptionalQRCodeInfoType) { MTROptionalQRCodeInfoTypeString, MTROptionalQRCodeInfoTypeInt32 };
 
+/**
+ * An optional information item present in the QR code the setup payload was
+ * initialized from.
+ */
 @interface MTROptionalQRCodeInfo : NSObject
-@property (nonatomic, copy) NSNumber * infoType;
+@property (nonatomic, assign) MTROptionalQRCodeInfoType infoType;
+// The numeric value of the TLV tag for this information item.
 @property (nonatomic, copy) NSNumber * tag;
-@property (nonatomic, copy) NSNumber * integerValue;
-@property (nonatomic, copy) NSString * stringValue;
+// Exactly one of integerValue and stringValue will be non-nil, depending on the
+// the value of "infoType".
+@property (nonatomic, copy, nullable) NSNumber * integerValue;
+@property (nonatomic, copy, nullable) NSString * stringValue;
 @end
 
+/**
+ * A setup payload that can be created from a pairing code and serialized to a
+ * pairing code.
+ */
 @interface MTRSetupPayload : NSObject <NSSecureCoding>
 
 @property (nonatomic, copy) NSNumber * version;
 @property (nonatomic, copy) NSNumber * vendorID;
 @property (nonatomic, copy) NSNumber * productID;
 @property (nonatomic, assign) MTRCommissioningFlow commissioningFlow;
 /**
- * rendezvousInformation is nil when the discovery capabilities bitmask is
- * unknown.
- *
- * Otherwise its value is made up of the MTRDiscoveryCapabilities flags.
+ * The value of discoveryCapabilities is made up of the various MTRDiscoveryCapabilities flags.
  */
-@property (nonatomic, copy, nullable) NSNumber * rendezvousInformation;
+@property (nonatomic, assign) MTRDiscoveryCapabilities discoveryCapabilities;
 @property (nonatomic, copy) NSNumber * discriminator;
+/**
+ * If hasShortDiscriminator is true, the discriminator value contains just the
+ * high 4 bits of the full discriminator.  For example, if
+ * hasShortDiscriminator is true and discriminator is 0xA, then the full
+ * discriminator can be anything in the range 0xA00 t0 0xAFF.
+ */
 @property (nonatomic, assign) BOOL hasShortDiscriminator;
-@property (nonatomic, copy) NSNumber * setUpPINCode;
+@property (nonatomic, copy) NSNumber * setupPasscode;
 
-@property (nonatomic, copy) NSString * serialNumber;
+@property (nonatomic, copy, nullable) NSString * serialNumber;
 - (nullable NSArray<MTROptionalQRCodeInfo *> *)getAllOptionalVendorData:(NSError * __autoreleasing *)error;
 
 /**
  * Generate a random Matter-valid setup passcode.
  */
 + (NSNumber *)generateRandomSetupPasscode;
 
+/**
+ * Create an MTRSetupPayload with the given onboarding payload.
+ *
+ * Will return nil on errors (e.g. if the onboarding payload cannot be parsed).
+ */
++ (MTRSetupPayload * _Nullable)setupPayloadWithOnboardingPayload:(NSString *)onboardingPayload
+                                                           error:(NSError * __autoreleasing *)error;
+
 /** Get 11 digit manual entry code from the setup payload. */
 - (nullable NSString *)manualEntryCode;