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