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.

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) {