Line data Source code
1 : /*
2 : * Copyright (c) 2021 Project CHIP Authors
3 : * All rights reserved.
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 : #pragma once
19 :
20 : #include <app-common/zap-generated/cluster-objects.h>
21 : #include <controller/CommissioningDelegate.h>
22 : #include <lib/core/CHIPError.h>
23 : #include <lib/core/NodeId.h>
24 : #include <lib/support/DLLUtil.h>
25 : #include <protocols/secure_channel/RendezvousParameters.h>
26 : #include <setup_payload/SetupPayload.h>
27 : #include <stdint.h>
28 :
29 : #include <optional>
30 :
31 : namespace chip {
32 : namespace Controller {
33 :
34 : /**
35 : * A delegate that can be notified of progress as a "pairing" (which might mean
36 : * "PASE session establishment" or "commissioning") proceeds.
37 : */
38 : class DLL_EXPORT DevicePairingDelegate
39 : {
40 : public:
41 19 : virtual ~DevicePairingDelegate() {}
42 :
43 : enum Status : uint8_t
44 : {
45 : SecurePairingSuccess = 0,
46 : SecurePairingFailed,
47 : };
48 :
49 : /**
50 : * @brief
51 : * Called when the pairing reaches a certain stage.
52 : *
53 : * @param status Current status of pairing
54 : */
55 0 : virtual void OnStatusUpdate(DevicePairingDelegate::Status status) {}
56 :
57 : /**
58 : * @brief
59 : * Called when PASE session establishment is complete (with success or error)
60 : *
61 : * @param error Error cause, if any
62 : */
63 0 : virtual void OnPairingComplete(CHIP_ERROR error) {}
64 :
65 : /**
66 : * @brief
67 : * Called when PASE session establishment is complete (with success or error)
68 : *
69 : * @param error Error cause, if any
70 : *
71 : * @param rendezvousParameters The RendezvousParameters that were used for PASE establishment.
72 : * If available, this helps identify which exact commissionee PASE
73 : * was established for. This will generally be present only when
74 : * PASE establishment succeeds.
75 : *
76 : * @param setupPayload The SetupPayload that was used for PASE establishment, if one is
77 : * available. This will generally be present only when PASE establishment
78 : * succeeds and the original input to commissioning was a payload string.
79 : * If the original input represented a concatenated QR code, this will
80 : * represent the actual payload that was used to successfully establish PASE
81 : * with the commissionee.
82 : */
83 0 : virtual void OnPairingComplete(CHIP_ERROR error, const std::optional<RendezvousParameters> & rendezvousParameters,
84 : const std::optional<SetupPayload> & setupPayload)
85 : {
86 0 : OnPairingComplete(error);
87 0 : }
88 :
89 : /**
90 : * @brief
91 : * Called when the pairing is deleted (with success or error)
92 : *
93 : * @param error Error cause, if any
94 : */
95 0 : virtual void OnPairingDeleted(CHIP_ERROR error) {}
96 :
97 : /**
98 : * Called when the commissioning process is complete (with success or error)
99 : */
100 0 : virtual void OnCommissioningComplete(NodeId deviceId, CHIP_ERROR error) {}
101 0 : virtual void OnCommissioningSuccess(PeerId peerId) {}
102 0 : virtual void OnCommissioningFailure(PeerId peerId, CHIP_ERROR error, CommissioningStage stageFailed,
103 : Optional<Credentials::AttestationVerificationResult> additionalErrorInfo)
104 0 : {}
105 :
106 : /**
107 : * @brief
108 : * Called when commissioning fails, with the full structured CompletionStatus from the
109 : * commissioning state machine. Provides access to detailed status that the 4-arg overload
110 : * above drops on the floor.
111 : *
112 : * Default implementation forwards to the legacy 4-arg overload above, so existing
113 : * delegates keep working unchanged. The legacy form only carries `err`, `failedStage`,
114 : * and `attestationResult` — the following CompletionStatus fields are silently dropped
115 : * when the default forwarder runs:
116 : *
117 : * - commissioningError (GeneralCommissioning cluster CommissioningErrorEnum)
118 : * - networkCommissioningStatus + connectNetworkErrorValue
119 : * - operationalCertStatus (OperationalCredentials NOCResponse status)
120 : * - commissioningDebugText (device-supplied text from ArmFailSafe /
121 : * SetRegulatoryConfig / CommissioningComplete)
122 : * - networkCommissioningDebugText (device-supplied text from NetworkConfig /
123 : * ConnectNetwork)
124 : *
125 : * Override this overload (instead of the 4-arg one) to receive those fields.
126 : */
127 2 : virtual void OnCommissioningFailure(PeerId peerId, const CompletionStatus & completionStatus)
128 : {
129 2 : OnCommissioningFailure(peerId, completionStatus.err, completionStatus.failedStage.ValueOr(CommissioningStage::kError),
130 2 : completionStatus.attestationResult);
131 2 : }
132 :
133 0 : virtual void OnCommissioningStatusUpdate(PeerId peerId, CommissioningStage stageCompleted, CHIP_ERROR error) {}
134 :
135 : /**
136 : * @brief
137 : * Called with the ReadCommissioningInfo returned from the target
138 : */
139 0 : virtual void OnReadCommissioningInfo(const ReadCommissioningInfo & info) {}
140 :
141 : /**
142 : * @brief
143 : * Called when MatchingFabricInfo returned from target
144 : */
145 0 : virtual void OnFabricCheck(NodeId matchingNodeId) {}
146 :
147 : /**
148 : * @brief
149 : * Called with the NetworkScanResponse returned from the target.
150 : *
151 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
152 : *
153 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
154 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
155 : * in order to resume the commissioning process.
156 : */
157 : virtual void
158 0 : OnScanNetworksSuccess(const app::Clusters::NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & dataResponse)
159 0 : {}
160 :
161 : /**
162 : * @brief
163 : * Called when the NetworkScan request fails.
164 : *
165 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
166 : *
167 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
168 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
169 : * in order to resume the commissioning process.
170 : */
171 0 : virtual void OnScanNetworksFailure(CHIP_ERROR error) {}
172 :
173 : /**
174 : * @brief
175 : * Called when the ICD registration information (ICD symmetric key, check-in node ID and monitored subject) is required.
176 : *
177 : * The DeviceCommissioner will be waiting in the kICDGetRegistrationInfo step and not advancing the commissioning process.
178 : *
179 : * The implementation should set the ICD registration info on the CommissioningParameters of the CommissioningDelegate
180 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.ICDRegistrationInfoReady()
181 : * in order to resume the commissioning process.
182 : *
183 : * Not called if the ICD registration info is provided up front.
184 : */
185 0 : virtual void OnICDRegistrationInfoRequired() {}
186 :
187 : /**
188 : * @brief
189 : * Called when the registration flow for the ICD completes.
190 : *
191 : * @param[in] icdNodeId The node id of the ICD.
192 : * @param[in] icdCounter The ICD Counter received from the device.
193 : */
194 0 : virtual void OnICDRegistrationComplete(ScopedNodeId icdNodeId, uint32_t icdCounter) {}
195 :
196 : /**
197 : * @brief
198 : * Called upon completion of the LIT ICD commissioning flow, when ICDStayActiveDuration is set
199 : * and the corresponding stayActive command response is received
200 : *
201 : * @param[in] icdNodeId The node id of the ICD.
202 : * @param[in] promisedActiveDurationMsec The actual duration that the ICD server can stay active
203 : * from the time it receives the StayActiveRequest command.
204 : */
205 0 : virtual void OnICDStayActiveComplete(ScopedNodeId icdNodeId, uint32_t promisedActiveDurationMsec) {}
206 :
207 : /**
208 : * @brief
209 : * Called when a commissioning stage starts.
210 : *
211 : * @param[in] peerId an identifier for the commissioning process. This is generally the
212 : * client-provided commissioning identifier before AddNOC and the actual
213 : * NodeID of the node after AddNoc, combined with the compressed fabric ID for
214 : * the fabric doing the commissioning.
215 : * @param[in] stageStarting the stage being started.
216 : */
217 0 : virtual void OnCommissioningStageStart(PeerId peerId, CommissioningStage stageStarting) {}
218 :
219 : /**
220 : * @brief
221 : * Called when Wi-Fi credentials are needed. If the call returns
222 : * CHIP_NO_ERROR, commissioning will pause until NetworkCredentialsReady()
223 : * is called on the CHIPDeviceController. This call must happen
224 : * asynchronously, after WiFiCredentialsNeeded has returned.
225 : *
226 : * @param[in] endpoint the endpoint that hosts the Network Commissioning cluster the credentials are needed for.
227 : */
228 0 : virtual CHIP_ERROR WiFiCredentialsNeeded(EndpointId endpoint) { return CHIP_ERROR_NOT_IMPLEMENTED; }
229 :
230 : /**
231 : * @brief
232 : * Called when Thread credentials are needed. If the call returns
233 : * CHIP_NO_ERROR, commissioning will pause until NetworkCredentialsReady()
234 : * is called on the CHIPDeviceController. This call must happen
235 : * asynchronously, after ThreadCredentialsNeeded has returned.
236 : *
237 : * @param[in] endpoint the endpoint that hosts the Network Commissioning cluster the credentials are needed for.
238 : */
239 0 : virtual CHIP_ERROR ThreadCredentialsNeeded(EndpointId endpoint) { return CHIP_ERROR_NOT_IMPLEMENTED; }
240 : };
241 :
242 : } // namespace Controller
243 : } // namespace chip
|
