Update Darwin availability annotations. (#27642)

* Update to the Fan Control renames from #27434.
* Put in the correct Darwin versions for fall release in availability.yaml.
* Move anything that is not 100% known to be stable right now to provisional for
  Darwin fall release in availability.yaml.
* Add backwards-compat shim for MTRFanControlWindSettingMask.
* Turn off darwin-framework-tool tests that would use the now-not-existing APIs.
* Fix availability annotations for initWithResponseValue for command response
  payloads.
* Replace non-generated MTR_NEWLY_* annotations with appropriate API_AVAILABLE
  and MTR_DEPRECATED.

Author: bzbarsky-apple

examples/darwin-framework-tool/templates/tests/ciTests.json

@@ -65,6 +65,50 @@
         "Test_TC_WTREMON_2_1",
         "Disabled due to using provisional Zeolite Filter Monitoring (ZeoliteFilterMonitoring) cluster:",
         "Test_TC_ZEOFREMON_1_1",
-        "Test_TC_ZEOFREMON_2_1"
+        "Test_TC_ZEOFREMON_2_1",
+        "Disabled due to AirQuality not being enabled in Matter.framework for now:",
+        "Test_TC_AIRQUAL_1_1",
+        "Test_TC_AIRQUAL_2_1",
+        "Disabled due to CarbonDioxideConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_CDOCONC_1_1",
+        "Test_TC_CDOCONC_2_1",
+        "Disabled due to CarbonMonoxideConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_CMOCONC_1_1",
+        "Test_TC_CMOCONC_2_1",
+        "Disabled due to FormaldehydeConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_FLDCONC_1_1",
+        "Test_TC_FLDCONC_2_1",
+        "Disabled due to NitrogenDioxideConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_NDOCONC_1_1",
+        "Test_TC_NDOCONC_2_1",
+        "Disabled due to OzoneConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_OZCONC_1_1",
+        "Test_TC_OZCONC_2_1",
+        "Disabled due to PM1ConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_PMHCONC_1_1",
+        "Test_TC_PMHCONC_2_1",
+        "Disabled due to PM2.5ConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_PMICONC_1_1",
+        "Test_TC_PMICONC_2_1",
+        "Disabled due to PM10ConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_PMKCONC_1_1",
+        "Test_TC_PMKCONC_2_1",
+        "Disabled due to RadonConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_RNCONC_1_1",
+        "Test_TC_RNCONC_2_1",
+        "Disabled due to TotalVolatileOrganicCompoundsConcentrationMeasurement not being enabled in Matter.framework for now:",
+        "Test_TC_TVOCCONC_1_1",
+        "Test_TC_TVOCCONC_2_1",
+        "Disabled due to FanControl AirFlowDirection attribute not being enabled in Matter.framework for now:",
+        "Test_TC_FAN_2_5",
+        "Disabled due to DoorLock UnboltDoor command not being enabled in Matter.framework for now:",
+        "Test_TC_DRLK_2_12",
+        "DL_LockUnlock",
+        "Disabled due to ActivatedCarbonFilterMonitoring not being enabled in Matter.framework for now:",
+        "Test_TC_ACFREMON_1_1",
+        "Test_TC_ACFREMON_2_1",
+        "Disabled due to HEPAFilterMonitoring not being enabled in Matter.framework for now:",
+        "Test_TC_HEPAFREMON_1_1",
+        "Test_TC_HEPAFREMON_2_1"
     ]
 }

examples/darwin-framework-tool/templates/tests/partials/test_cluster.zapt

@@ -58,8 +58,15 @@ class {{filename}}: public TestCommandBridge
               return;
           }
           {{/if}}
+          {{! EventList marked provisional for now }}
+          {{#if (and isReadAttribute
+                     (isStrEqual (asUpperCamelCase (or attribute "") preserveAcronyms=true) "EventList"))}}
+          NextTest();
+          return;
+          {{else}}
           err = Test{{asUpperCamelCase label}}_{{index}}();
           break;
+          {{/if}}
         {{/chip_tests_items}}
       }
 
@@ -105,6 +112,9 @@ class {{filename}}: public TestCommandBridge
     {{/chip_tests_config}}
 
     {{#chip_tests_items}}
+    {{! EventList marked provisional for now }}
+    {{#unless (and isReadAttribute
+                   (isStrEqual (asUpperCamelCase (or attribute "") preserveAcronyms=true) "EventList"))}}
     {{#if async}}
     bool testSendCluster{{parent.filename}}_{{index}}_{{asUpperCamelCase command}}_Fulfilled = false;
     {{/if}}
@@ -257,7 +267,8 @@ class {{filename}}: public TestCommandBridge
     return CHIP_NO_ERROR;
     {{/if}}
   }
-{{/chip_tests_items}}
+  {{/unless}}
+  {{/chip_tests_items}}
 
 };
 

src/darwin/Framework/CHIP/MTRBackwardsCompatShims.h

@@ -17,6 +17,7 @@
 #import <Foundation/Foundation.h>
 
 #import <Matter/MTRCommandPayloadsObjc.h>
+#import <Matter/MTRDefines.h>
 #import <Matter/MTRStructsObjc.h>
 
 /**
@@ -30,9 +31,24 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * This command used to incorrectly have a groupKeySetIDs field.
  */
-@property (nonatomic, copy) NSArray * groupKeySetIDs API_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
-    MTR_NEWLY_DEPRECATED("This field has been removed");
+@property (nonatomic, copy) NSArray * groupKeySetIDs MTR_DEPRECATED(
+    "This field has been removed", ios(16.1, 17.0), macos(13.0, 14.0), watchos(9.1, 10.0), tvos(16.1, 17.0));
 
 @end
 
+/**
+ * FanControl used to have WindSettingMask and WindSupportMask that had
+ * identical values.  Those got replaced with a single WindBitmap.  We codegen
+ * WindSupportMask as an alias of WindBitmap, but we need a manual shim for
+ * WindSettingMask.
+ */
+typedef NS_OPTIONS(uint8_t, MTRFanControlWindSettingMask) {
+    MTRFanControlWindSettingMaskSleepWind MTR_DEPRECATED(
+        "Please use MTRFanControlWindBitmapSleepWind", ios(16.1, 17.0), macos(13.0, 14.0), watchos(9.1, 10.0), tvos(16.1, 17.0))
+    = 0x1,
+    MTRFanControlWindSettingMaskNaturalWind MTR_DEPRECATED(
+        "Please use MTRFanControlWindBitmapNaturalWind", ios(16.1, 17.0), macos(13.0, 14.0), watchos(9.1, 10.0), tvos(16.1, 17.0))
+    = 0x2,
+} MTR_DEPRECATED("Please use MTRFanControlWindBitmap", ios(16.1, 17.0), macos(13.0, 14.0), watchos(9.1, 10.0), tvos(16.1, 17.0));
+
 NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRBaseDevice.h

@@ -154,31 +154,36 @@ typedef NS_ENUM(uint8_t, MTRTransportType) {
  *
  * nil is used to represent wildcards.
  */
-MTR_NEWLY_AVAILABLE
+API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
 @interface MTRAttributeRequestPath : NSObject <NSCopying>
-@property (nonatomic, readonly, copy, nullable) NSNumber * endpoint;
-@property (nonatomic, readonly, copy, nullable) NSNumber * cluster;
-@property (nonatomic, readonly, copy, nullable) NSNumber * attribute;
+@property (nonatomic, readonly, copy, nullable) NSNumber * endpoint API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
+    ;
+@property (nonatomic, readonly, copy, nullable) NSNumber * cluster API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
+@property (nonatomic, readonly, copy, nullable)
+    NSNumber * attribute API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 + (MTRAttributeRequestPath *)requestPathWithEndpointID:(NSNumber * _Nullable)endpointID
                                              clusterID:(NSNumber * _Nullable)clusterID
-                                           attributeID:(NSNumber * _Nullable)attributeID MTR_NEWLY_AVAILABLE;
+                                           attributeID:(NSNumber * _Nullable)attributeID
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 @end
 
 /**
  * A path indicating an event being requested (for read or subscribe).
  *
  * nil is used to represent wildcards.
  */
-MTR_NEWLY_AVAILABLE
+API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
 @interface MTREventRequestPath : NSObject <NSCopying>
-@property (nonatomic, readonly, copy, nullable) NSNumber * endpoint;
-@property (nonatomic, readonly, copy, nullable) NSNumber * cluster;
-@property (nonatomic, readonly, copy, nullable) NSNumber * event;
+@property (nonatomic, readonly, copy, nullable) NSNumber * endpoint API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
+    ;
+@property (nonatomic, readonly, copy, nullable) NSNumber * cluster API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
+@property (nonatomic, readonly, copy, nullable) NSNumber * event API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 + (MTREventRequestPath *)requestPathWithEndpointID:(NSNumber * _Nullable)endpointID
                                          clusterID:(NSNumber * _Nullable)clusterID
-                                           eventID:(NSNumber * _Nullable)eventID MTR_NEWLY_AVAILABLE;
+                                           eventID:(NSNumber * _Nullable)eventID
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 @end
 
 @interface MTRBaseDevice : NSObject
@@ -299,7 +304,7 @@ MTR_NEWLY_AVAILABLE
                 eventPaths:(NSArray<MTREventRequestPath *> * _Nullable)eventPaths
                     params:(MTRReadParams * _Nullable)params
                      queue:(dispatch_queue_t)queue
-                completion:(MTRDeviceResponseHandler)completion MTR_NEWLY_AVAILABLE;
+                completion:(MTRDeviceResponseHandler)completion API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Write to attribute in a designated attribute path
@@ -418,7 +423,8 @@ MTR_NEWLY_AVAILABLE
                             queue:(dispatch_queue_t)queue
                     reportHandler:(MTRDeviceResponseHandler)reportHandler
           subscriptionEstablished:(MTRSubscriptionEstablishedHandler _Nullable)subscriptionEstablished
-          resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled MTR_NEWLY_AVAILABLE;
+          resubscriptionScheduled:(MTRDeviceResubscriptionScheduledHandler _Nullable)resubscriptionScheduled
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Deregister all local report handlers for a remote device
@@ -466,7 +472,8 @@ MTR_NEWLY_AVAILABLE
 - (void)openCommissioningWindowWithDiscriminator:(NSNumber *)discriminator
                                         duration:(NSNumber *)duration
                                            queue:(dispatch_queue_t)queue
-                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion MTR_NEWLY_AVAILABLE;
+                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Reads events from the device.
@@ -633,7 +640,8 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  * * The data does not match the known schema.
  */
 - (nullable instancetype)initWithResponseValue:(NSDictionary<NSString *, id> *)responseValue
-                                         error:(NSError * __autoreleasing *)error MTR_NEWLY_AVAILABLE;
+                                         error:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 @end
 
@@ -706,7 +714,8 @@ typedef NS_ENUM(NSUInteger, MTREventPriority) {
  * * The data does not match the known schema.
  */
 - (nullable instancetype)initWithResponseValue:(NSDictionary<NSString *, id> *)responseValue
-                                         error:(NSError * __autoreleasing *)error MTR_NEWLY_AVAILABLE;
+                                         error:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 @end
 

src/darwin/Framework/CHIP/MTRCSRInfo.h

@@ -62,7 +62,8 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
                    csrNonce:(NSData *)csrNonce
              csrElementsTLV:(MTRTLVBytes)csrElementsTLV
        attestationSignature:(NSData *)attestationSignature
-    MTR_NEWLY_DEPRECATED("Please use one of the initializers that validates the input");
+    MTR_DEPRECATED("Please use one of the initializers that validates the input", ios(16.4, 17.0), macos(13.3, 14.0),
+        watchos(9.4, 10.0), tvos(16.4, 17.0));
 
 /**
  * Initialize an MTROperationalCSRInfo by providing the csrNonce (for example,
@@ -73,7 +74,8 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  */
 - (nullable instancetype)initWithCSRNonce:(NSData *)csrNonce
                            csrElementsTLV:(MTRTLVBytes)csrElementsTLV
-                     attestationSignature:(NSData *)attestationSignature MTR_NEWLY_AVAILABLE;
+                     attestationSignature:(NSData *)attestationSignature
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Initialize an MTROperationalCSRInfo by providing just the csrElementsTLV and
@@ -83,15 +85,16 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  * fails.
  */
 - (nullable instancetype)initWithCSRElementsTLV:(MTRTLVBytes)csrElementsTLV
-                           attestationSignature:(NSData *)attestationSignature MTR_NEWLY_AVAILABLE;
+                           attestationSignature:(NSData *)attestationSignature
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Initialize an MTROperationalCSRInfo by providing an
  * MTROperationalCredentialsClusterCSRResponseParams.  This will extract the
  * relevant fields from the response data.
  */
 - (nullable instancetype)initWithCSRResponseParams:(MTROperationalCredentialsClusterCSRResponseParams *)responseParams
-    MTR_NEWLY_AVAILABLE;
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 @end
 
 MTR_DEPRECATED("Please use MTROperationalCSRInfo", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4))

src/darwin/Framework/CHIP/MTRCommissionableBrowserDelegate.h

@@ -22,7 +22,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-MTR_NEWLY_AVAILABLE
+API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
 @protocol MTRCommissionableBrowserDelegate <NSObject>
 /**
  * Tells the delegate the commissionable manager discovered a device while scanning for devices.

src/darwin/Framework/CHIP/MTRCommissionableBrowserResult.h

@@ -19,7 +19,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-MTR_NEWLY_AVAILABLE
+API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
 @interface MTRCommissionableBrowserResult : NSObject
 
 /**

src/darwin/Framework/CHIP/MTRCommissioningParameters.h

@@ -86,15 +86,15 @@ NS_ASSUME_NONNULL_BEGIN
  *
  * Defaults to NO.
  */
-@property (nonatomic, assign) BOOL skipCommissioningComplete MTR_NEWLY_AVAILABLE;
+@property (nonatomic, assign) BOOL skipCommissioningComplete API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * The country code to provide to the device during commissioning.
  *
  * If not nil, this must be a 2-character ISO 3166-1 country code, which the
  * device can use to decide on things like radio communications bands.
  */
-@property (nonatomic, copy, nullable) NSString * countryCode MTR_NEWLY_AVAILABLE;
+@property (nonatomic, copy, nullable) NSString * countryCode API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 @end
 

src/darwin/Framework/CHIP/MTRDevice.h

@@ -17,6 +17,7 @@
 
 #import <Foundation/Foundation.h>
 #import <Matter/MTRBaseDevice.h>
+#import <Matter/MTRDefines.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -198,7 +199,8 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
 - (void)openCommissioningWindowWithDiscriminator:(NSNumber *)discriminator
                                         duration:(NSNumber *)duration
                                            queue:(dispatch_queue_t)queue
-                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion MTR_NEWLY_AVAILABLE;
+                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 @end
 

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -18,6 +18,7 @@
 #import <Foundation/Foundation.h>
 
 #import <Matter/MTRCommissionableBrowserDelegate.h>
+#import <Matter/MTRDefines.h>
 #import <Matter/MTROperationalCertificateIssuer.h>
 
 @class MTRBaseDevice;
@@ -117,7 +118,8 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
 - (BOOL)setupCommissioningSessionWithDiscoveredDevice:(MTRCommissionableBrowserResult *)discoveredDevice
                                               payload:(MTRSetupPayload *)payload
                                             newNodeID:(NSNumber *)newNodeID
-                                                error:(NSError * __autoreleasing *)error MTR_NEWLY_AVAILABLE;
+                                                error:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Commission the node with the given node ID.  The node ID must match the node
@@ -180,14 +182,14 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
  * This method will fail if the controller factory is not running or the browse has already been started.
  */
 - (BOOL)startBrowseForCommissionables:(id<MTRCommissionableBrowserDelegate>)delegate
-                                queue:(dispatch_queue_t)queue MTR_NEWLY_AVAILABLE;
+                                queue:(dispatch_queue_t)queue API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Stop scanning for commissionable devices.
  *
  * This method will fail if the controller factory is not running or the browse has not been started.
  */
-- (BOOL)stopBrowseForCommissionables MTR_NEWLY_AVAILABLE;
+- (BOOL)stopBrowseForCommissionables API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Return the attestation challenge for the secure session of the device being commissioned.

src/darwin/Framework/CHIP/MTRDeviceControllerDelegate.h

@@ -15,6 +15,7 @@
  *    limitations under the License.
  */
 
+#import <Foundation/Foundation.h>
 #import <Matter/MTRDefines.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -31,7 +32,7 @@ typedef NS_ENUM(NSInteger, MTRCommissioningStatus) {
 /**
  * A representation of a (vendor, product) pair that identifies a specific product.
  */
-MTR_NEWLY_AVAILABLE
+API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0))
 @interface MTRProductIdentity : NSObject
 
 @property (nonatomic, copy, readonly) NSNumber * vendorID;
@@ -66,7 +67,9 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  * Notify the delegate when commissioning is completed.
  */
 - (void)controller:(MTRDeviceController *)controller
-    commissioningComplete:(NSError * _Nullable)error MTR_NEWLY_DEPRECATED("Please use controller:commissioningComplete:nodeID:");
+    commissioningComplete:(NSError * _Nullable)error
+    MTR_DEPRECATED("Please use controller:commissioningComplete:nodeID:", ios(16.4, 17.0), macos(13.3, 14.0), watchos(9.4, 10.0),
+        tvos(16.4, 17.0));
 
 /**
  * Notify the delegate when commissioning is completed.
@@ -77,7 +80,7 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  */
 - (void)controller:(MTRDeviceController *)controller
     commissioningComplete:(NSError * _Nullable)error
-                   nodeID:(NSNumber * _Nullable)nodeID MTR_NEWLY_AVAILABLE;
+                   nodeID:(NSNumber * _Nullable)nodeID API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 
 /**
  * Notify the delegate when commissioning infomation has been read from the Basic
@@ -86,7 +89,8 @@ API_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  * At the point when this notification happens, device attestation has not been performed yet,
  * so the information delivered by this notification should not be trusted.
  */
-- (void)controller:(MTRDeviceController *)controller readCommissioningInfo:(MTRProductIdentity *)info MTR_NEWLY_AVAILABLE;
+- (void)controller:(MTRDeviceController *)controller
+    readCommissioningInfo:(MTRProductIdentity *)info API_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
 @end
 
 typedef NS_ENUM(NSUInteger, MTRPairingStatus) {