Skip to content

Commit 96813aa

Browse files
kiel-applekiel-apple
authored
[Darwin] Duplicate MTRDeviceController with git cp (#34828)
* Keep MTRDeviceController.h * Copy MTRDeviceController.h into MTRDeviceController_Concrete.h * Set back MTRDeviceController.h file * Keep MTRDeviceController.mm * Copy MTRDeviceController.mm into MTRDeviceController_Concrete.mm * Set back MTRDeviceController.mm file
1 parent faef75c commit 96813aa

File tree

2 files changed

+2331
-0
lines changed

2 files changed

+2331
-0
lines changed

‎src/darwin/Framework/CHIP/MTRDeviceController_Concrete.h

+343
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,343 @@
1+
/**
2+
*
3+
* Copyright (c) 2020-2023 Project CHIP Authors
4+
*
5+
* Licensed under the Apache License, Version 2.0 (the "License");
6+
* you may not use this file except in compliance with the License.
7+
* You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
#import <Foundation/Foundation.h>
19+
20+
#import <Matter/MTRCommissionableBrowserDelegate.h>
21+
#import <Matter/MTRDefines.h>
22+
#import <Matter/MTROperationalCertificateIssuer.h>
23+
24+
@class MTRBaseDevice;
25+
@class MTRServerEndpoint; // Defined in MTRServerEndpoint.h, which imports MTRAccessGrant.h, which imports MTRBaseClusters.h, which imports this file, so we can't import it.
26+
27+
@class MTRDeviceControllerAbstractParameters;
28+
29+
NS_ASSUME_NONNULL_BEGIN
30+
31+
MTR_DEPRECATED("Please use MTRBaseDevice deviceWithNodeID", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4))
32+
typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NSError * _Nullable error);
33+
34+
@class MTRCommissioningParameters;
35+
@class MTRCommissionableBrowserResult;
36+
@class MTRSetupPayload;
37+
@protocol MTRDevicePairingDelegate;
38+
@protocol MTRDeviceControllerDelegate;
39+
40+
MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
41+
@interface MTRDeviceController : NSObject
42+
43+
/**
44+
* Controllers are created via the MTRDeviceControllerFactory object or
45+
* initialized via initWithParameters:error:.
46+
*/
47+
- (instancetype)init NS_UNAVAILABLE;
48+
+ (instancetype)new NS_UNAVAILABLE;
49+
50+
/**
51+
* Initialize a device controller with the provided parameters. This will:
52+
*
53+
* 1) Auto-start the MTRDeviceControllerFactory in storage-per-controller mode
54+
* if it has not already been started.
55+
* 2) Return nil or a running controller.
56+
*
57+
* Once this returns non-nil, it's the caller's responsibility to call shutdown
58+
* on the controller to avoid leaking it.
59+
*/
60+
- (nullable instancetype)initWithParameters:(MTRDeviceControllerAbstractParameters *)parameters
61+
error:(NSError * __autoreleasing *)error MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
62+
63+
/**
64+
* If true, the controller has not been shut down yet.
65+
*/
66+
@property (readonly, nonatomic, getter=isRunning) BOOL running;
67+
68+
/**
69+
* The ID assigned to this controller at creation time.
70+
*/
71+
@property (readonly, nonatomic) NSUUID * uniqueIdentifier MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
72+
73+
/**
74+
* Return the Node ID assigned to the controller. Will return nil if the
75+
* controller is not running (and hence does not know its node id).
76+
*/
77+
@property (readonly, nonatomic, nullable)
78+
NSNumber * controllerNodeID MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
79+
80+
/**
81+
* Set up a commissioning session for a device, using the provided setup payload
82+
* to discover it and connect to it.
83+
*
84+
* @param payload a setup payload (probably created from a QR code or numeric
85+
* code onboarding payload).
86+
* @param newNodeID the planned node id for the node.
87+
* @error error indication if discovery can't start at all (e.g. because the
88+
* setup payload is invalid).
89+
*
90+
* The IP and port for the device will be discovered automatically based on the
91+
* provided discriminator.
92+
*
93+
* Then a PASE session will be established with the device, unless an error
94+
* occurs. MTRDeviceControllerDelegate will be notified as follows:
95+
*
96+
* * Discovery fails: onStatusUpdate with MTRCommissioningStatusFailed.
97+
*
98+
* * Discovery succeeds but commissioning session setup fails: onPairingComplete
99+
* with an error.
100+
*
101+
* * Commissioning session setup succeeds: onPairingComplete with no error.
102+
*
103+
* Once a commissioning session is set up, getDeviceBeingCommissioned
104+
* can be used to get an MTRBaseDevice and discover what sort of network
105+
* credentials the device might need, and commissionDevice can be used to
106+
* commission the device.
107+
*/
108+
- (BOOL)setupCommissioningSessionWithPayload:(MTRSetupPayload *)payload
109+
newNodeID:(NSNumber *)newNodeID
110+
error:(NSError * __autoreleasing *)error
111+
MTR_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
112+
113+
/**
114+
* Set up a commissioning session for a device, using the provided discovered
115+
* result to connect to it.
116+
*
117+
* @param discoveredDevice a previously discovered device.
118+
* @param payload a setup payload (probably created from a QR code or numeric
119+
* code onboarding payload).
120+
* @param newNodeID the planned node id for the node.
121+
* @error error indication if the commissioning session establishment can't start at all.
122+
*
123+
* The connection information for the device will be retrieved from the discovered device.
124+
* A device discovered over DNS-SD will use the discovered IPs/ports, while a device discovered
125+
* over BLE will use the underlying CBPeripheral.
126+
*
127+
* Then a PASE session will be established with the device, unless an error
128+
* occurs. MTRDeviceControllerDelegate will be notified as follows:
129+
*
130+
* * Invalid connection information: onStatusUpdate with MTRCommissioningStatusFailed.
131+
*
132+
* * Commissioning session setup fails: onPairingComplete with an error.
133+
*
134+
* * Commissioning session setup succeeds: onPairingComplete with no error.
135+
*
136+
* Once a commissioning session is set up, getDeviceBeingCommissioned
137+
* can be used to get an MTRBaseDevice and discover what sort of network
138+
* credentials the device might need, and commissionDevice can be used to
139+
* commission the device.
140+
*/
141+
- (BOOL)setupCommissioningSessionWithDiscoveredDevice:(MTRCommissionableBrowserResult *)discoveredDevice
142+
payload:(MTRSetupPayload *)payload
143+
newNodeID:(NSNumber *)newNodeID
144+
error:(NSError * __autoreleasing *)error
145+
MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
146+
147+
/**
148+
* Commission the node with the given node ID. The node ID must match the node
149+
* ID that was used to set up the commissioning session.
150+
*/
151+
- (BOOL)commissionNodeWithID:(NSNumber *)nodeID
152+
commissioningParams:(MTRCommissioningParameters *)commissioningParams
153+
error:(NSError * __autoreleasing *)error MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
154+
155+
/**
156+
* Call this method after MTRDeviceAttestationDelegate
157+
* deviceAttestationFailedForController:opaqueDeviceHandle:error: or
158+
* deviceAttestationCompletedForController:opaqueDeviceHandle:attestationDeviceInfo:error:
159+
* is called to continue commissioning the device.
160+
*/
161+
- (BOOL)continueCommissioningDevice:(void *)opaqueDeviceHandle
162+
ignoreAttestationFailure:(BOOL)ignoreAttestationFailure
163+
error:(NSError * __autoreleasing *)error;
164+
165+
/**
166+
* Cancel commissioning for the given node id. This will shut down any existing
167+
* commissioning session for that node id.
168+
*/
169+
- (BOOL)cancelCommissioningForNodeID:(NSNumber *)nodeID
170+
error:(NSError * __autoreleasing *)error
171+
MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
172+
173+
/**
174+
* Get an MTRBaseDevice for a commissioning session that was set up for the
175+
* given node ID. Returns nil if no such commissioning session is available.
176+
*/
177+
- (nullable MTRBaseDevice *)deviceBeingCommissionedWithNodeID:(NSNumber *)nodeID
178+
error:(NSError * __autoreleasing *)error
179+
MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
180+
181+
- (void)preWarmCommissioningSession MTR_DEPRECATED("-[MTRDeviceControllerFactory preWarmCommissioningSession]", ios(16.4, 17.6), macos(13.3, 14.6), watchos(9.4, 10.6), tvos(16.4, 17.6));
182+
183+
/**
184+
* Set the Delegate for the device controller as well as the Queue on which the Delegate callbacks will be triggered
185+
*
186+
* @param[in] delegate The delegate the commissioning process should use
187+
*
188+
* @param[in] queue The queue on which the callbacks will be delivered
189+
*/
190+
- (void)setDeviceControllerDelegate:(id<MTRDeviceControllerDelegate>)delegate
191+
queue:(dispatch_queue_t)queue MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
192+
193+
/**
194+
* Start scanning for commissionable devices.
195+
*
196+
* This method will fail if the controller factory is not running or the browse has already been started.
197+
*/
198+
- (BOOL)startBrowseForCommissionables:(id<MTRCommissionableBrowserDelegate>)delegate
199+
queue:(dispatch_queue_t)queue MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
200+
201+
/**
202+
* Stop scanning for commissionable devices.
203+
*
204+
* This method will fail if the controller factory is not running or the browse has not been started.
205+
*/
206+
- (BOOL)stopBrowseForCommissionables MTR_AVAILABLE(ios(17.0), macos(14.0), watchos(10.0), tvos(17.0));
207+
208+
/**
209+
* Return the attestation challenge for the secure session of the device being commissioned.
210+
*
211+
* Attempts to retrieve the attestation challenge for a commissionee with the given Device ID.
212+
* Returns nil if given Device ID does not match an active commissionee, or if a Secure Session is not availale.
213+
*/
214+
- (NSData * _Nullable)attestationChallengeForDeviceID:(NSNumber *)deviceID
215+
MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
216+
217+
/**
218+
* Add a server endpoint for this controller. The endpoint starts off enabled.
219+
*
220+
* Will fail in the following cases:
221+
*
222+
* 1) There is already an endpoint defined with the given endpoint id.
223+
* 2) There are too many endpoints defined already.
224+
*/
225+
- (BOOL)addServerEndpoint:(MTRServerEndpoint *)endpoint MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
226+
227+
/**
228+
* Remove the given server endpoint from this controller. If the endpoint is
229+
* not attached to this controller, will just call the completion and do nothing
230+
* else.
231+
*/
232+
- (void)removeServerEndpoint:(MTRServerEndpoint *)endpoint queue:(dispatch_queue_t)queue completion:(dispatch_block_t)completion MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
233+
234+
/**
235+
* Remove the given server endpoint without being notified when the removal
236+
* completes.
237+
*/
238+
- (void)removeServerEndpoint:(MTRServerEndpoint *)endpoint MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
239+
240+
/**
241+
* Compute a PASE verifier for the desired setup passcode.
242+
*
243+
* @param[in] setupPasscode The desired passcode to use.
244+
* @param[in] iterations The number of iterations to use when generating the verifier.
245+
* @param[in] salt The 16-byte salt for verifier computation.
246+
*
247+
* Returns nil on errors (e.g. salt has the wrong size), otherwise the computed
248+
* verifier bytes.
249+
*/
250+
+ (nullable NSData *)computePASEVerifierForSetupPasscode:(NSNumber *)setupPasscode
251+
iterations:(NSNumber *)iterations
252+
salt:(NSData *)salt
253+
error:(NSError * __autoreleasing *)error
254+
MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
255+
256+
/**
257+
* Shut down the controller. Calls to shutdown after the first one are NO-OPs.
258+
* This must be called, either directly or via shutting down the
259+
* MTRDeviceControllerFactory, to avoid leaking the controller.
260+
*/
261+
- (void)shutdown;
262+
263+
@end
264+
265+
@interface MTRDeviceController (Deprecated)
266+
267+
@property (readonly, nonatomic, nullable) NSNumber * controllerNodeId MTR_DEPRECATED(
268+
"Please use controllerNodeID", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
269+
270+
- (nullable NSData *)fetchAttestationChallengeForDeviceId:(uint64_t)deviceId
271+
MTR_DEPRECATED(
272+
"Please use attestationChallengeForDeviceID", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
273+
274+
- (BOOL)getBaseDevice:(uint64_t)deviceID
275+
queue:(dispatch_queue_t)queue
276+
completionHandler:(MTRDeviceConnectionCallback)completionHandler
277+
MTR_DEPRECATED("Please use [MTRBaseDevice deviceWithNodeID:controller:]", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4),
278+
tvos(16.1, 16.4));
279+
280+
- (BOOL)pairDevice:(uint64_t)deviceID
281+
discriminator:(uint16_t)discriminator
282+
setupPINCode:(uint32_t)setupPINCode
283+
error:(NSError * __autoreleasing *)error
284+
MTR_DEPRECATED("Please use setupCommissioningSessionWithPayload:newNodeID:error:", ios(16.1, 16.4), macos(13.0, 13.3),
285+
watchos(9.1, 9.4), tvos(16.1, 16.4));
286+
- (BOOL)pairDevice:(uint64_t)deviceID
287+
address:(NSString *)address
288+
port:(uint16_t)port
289+
setupPINCode:(uint32_t)setupPINCode
290+
error:(NSError * __autoreleasing *)error
291+
MTR_DEPRECATED("Please use setupCommissioningSessionWithPayload:newNodeID:error:", ios(16.1, 16.4), macos(13.0, 13.3),
292+
watchos(9.1, 9.4), tvos(16.1, 16.4));
293+
- (BOOL)pairDevice:(uint64_t)deviceID
294+
onboardingPayload:(NSString *)onboardingPayload
295+
error:(NSError * __autoreleasing *)error
296+
MTR_DEPRECATED("Please use setupCommissioningSessionWithPayload:newNodeID:error:", ios(16.1, 16.4), macos(13.0, 13.3),
297+
watchos(9.1, 9.4), tvos(16.1, 16.4));
298+
- (BOOL)commissionDevice:(uint64_t)deviceId
299+
commissioningParams:(MTRCommissioningParameters *)commissioningParams
300+
error:(NSError * __autoreleasing *)error
301+
MTR_DEPRECATED("Please use commissionNodeWithID:commissioningParams:error:", ios(16.1, 16.4), macos(13.0, 13.3),
302+
watchos(9.1, 9.4), tvos(16.1, 16.4));
303+
304+
- (BOOL)stopDevicePairing:(uint64_t)deviceID
305+
error:(NSError * __autoreleasing *)error
306+
MTR_DEPRECATED(
307+
"Please use cancelCommissioningForNodeID:error:", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
308+
309+
- (nullable MTRBaseDevice *)getDeviceBeingCommissioned:(uint64_t)deviceId
310+
error:(NSError * __autoreleasing *)error
311+
MTR_DEPRECATED("Please use deviceBeingCommissionedWithNodeID:error:", ios(16.1, 16.4), macos(13.0, 13.3), watchos(9.1, 9.4),
312+
tvos(16.1, 16.4));
313+
314+
- (BOOL)openPairingWindow:(uint64_t)deviceID
315+
duration:(NSUInteger)duration
316+
error:(NSError * __autoreleasing *)error
317+
MTR_DEPRECATED("Please use MTRDevice or MTRBaseDevice openCommissioningWindowWithSetupPasscode", ios(16.1, 16.4),
318+
macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
319+
- (nullable NSString *)openPairingWindowWithPIN:(uint64_t)deviceID
320+
duration:(NSUInteger)duration
321+
discriminator:(NSUInteger)discriminator
322+
setupPIN:(NSUInteger)setupPIN
323+
error:(NSError * __autoreleasing *)error
324+
MTR_DEPRECATED("Please use MTRDevice or MTRBaseDevice openCommissioningWindowWithSetupPasscode", ios(16.1, 16.4),
325+
macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
326+
327+
- (nullable NSData *)computePaseVerifier:(uint32_t)setupPincode
328+
iterations:(uint32_t)iterations
329+
salt:(NSData *)salt
330+
MTR_DEPRECATED("Please use computePASEVerifierForSetupPasscode:iterations:salt:error:", ios(16.1, 16.4), macos(13.0, 13.3),
331+
watchos(9.1, 9.4), tvos(16.1, 16.4));
332+
333+
- (void)setPairingDelegate:(id<MTRDevicePairingDelegate>)delegate
334+
queue:(dispatch_queue_t)queue MTR_DEPRECATED("Please use setDeviceControllerDelegate:", ios(16.1, 16.4),
335+
macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
336+
337+
- (void)setNocChainIssuer:(id<MTRNOCChainIssuer>)nocChainIssuer
338+
queue:(dispatch_queue_t)queue
339+
MTR_DEPRECATED("Please set the operationalCertificateIssuer in the MTRDeviceControllerStartupParams instead.", ios(16.1, 16.4),
340+
macos(13.0, 13.3), watchos(9.1, 9.4), tvos(16.1, 16.4));
341+
@end
342+
343+
NS_ASSUME_NONNULL_END

0 commit comments

Comments
 (0)