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