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 0 : 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 0 : virtual void OnCommissioningStatusUpdate(PeerId peerId, CommissioningStage stageCompleted, CHIP_ERROR error) {}
107 :
108 : /**
109 : * @brief
110 : * Called with the ReadCommissioningInfo returned from the target
111 : */
112 0 : virtual void OnReadCommissioningInfo(const ReadCommissioningInfo & info) {}
113 :
114 : /**
115 : * @brief
116 : * Called when MatchingFabricInfo returned from target
117 : */
118 0 : virtual void OnFabricCheck(NodeId matchingNodeId) {}
119 :
120 : /**
121 : * @brief
122 : * Called with the NetworkScanResponse returned from the target.
123 : *
124 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
125 : *
126 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
127 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
128 : * in order to resume the commissioning process.
129 : */
130 : virtual void
131 0 : OnScanNetworksSuccess(const app::Clusters::NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & dataResponse)
132 0 : {}
133 :
134 : /**
135 : * @brief
136 : * Called when the NetworkScan request fails.
137 : *
138 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
139 : *
140 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
141 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
142 : * in order to resume the commissioning process.
143 : */
144 0 : virtual void OnScanNetworksFailure(CHIP_ERROR error) {}
145 :
146 : /**
147 : * @brief
148 : * Called when the ICD registration information (ICD symmetric key, check-in node ID and monitored subject) is required.
149 : *
150 : * The DeviceCommissioner will be waiting in the kICDGetRegistrationInfo step and not advancing the commissioning process.
151 : *
152 : * The implementation should set the ICD registration info on the CommissioningParameters of the CommissioningDelegate
153 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.ICDRegistrationInfoReady()
154 : * in order to resume the commissioning process.
155 : *
156 : * Not called if the ICD registration info is provided up front.
157 : */
158 0 : virtual void OnICDRegistrationInfoRequired() {}
159 :
160 : /**
161 : * @brief
162 : * Called when the registration flow for the ICD completes.
163 : *
164 : * @param[in] icdNodeId The node id of the ICD.
165 : * @param[in] icdCounter The ICD Counter received from the device.
166 : */
167 0 : virtual void OnICDRegistrationComplete(ScopedNodeId icdNodeId, uint32_t icdCounter) {}
168 :
169 : /**
170 : * @brief
171 : * Called upon completion of the LIT ICD commissioning flow, when ICDStayActiveDuration is set
172 : * and the corresponding stayActive command response is received
173 : *
174 : * @param[in] icdNodeId The node id of the ICD.
175 : * @param[in] promisedActiveDurationMsec The actual duration that the ICD server can stay active
176 : * from the time it receives the StayActiveRequest command.
177 : */
178 0 : virtual void OnICDStayActiveComplete(ScopedNodeId icdNodeId, uint32_t promisedActiveDurationMsec) {}
179 :
180 : /**
181 : * @brief
182 : * Called when a commissioning stage starts.
183 : *
184 : * @param[in] peerId an identifier for the commissioning process. This is generally the
185 : * client-provided commissioning identifier before AddNOC and the actual
186 : * NodeID of the node after AddNoc, combined with the compressed fabric ID for
187 : * the fabric doing the commissioning.
188 : * @param[in] stageStarting the stage being started.
189 : */
190 0 : virtual void OnCommissioningStageStart(PeerId peerId, CommissioningStage stageStarting) {}
191 :
192 : /**
193 : * @brief
194 : * Called when Wi-Fi credentials are needed. If the call returns
195 : * CHIP_NO_ERROR, commissioning will pause until NetworkCredentialsReady()
196 : * is called on the CHIPDeviceController. This call must happen
197 : * asynchronously, after WiFiCredentialsNeeded has returned.
198 : *
199 : * @param[in] endpoint the endpoint that hosts the Network Commissioning cluster the credentials are needed for.
200 : */
201 0 : virtual CHIP_ERROR WiFiCredentialsNeeded(EndpointId endpoint) { return CHIP_ERROR_NOT_IMPLEMENTED; }
202 :
203 : /**
204 : * @brief
205 : * Called when Thread credentials are needed. If the call returns
206 : * CHIP_NO_ERROR, commissioning will pause until NetworkCredentialsReady()
207 : * is called on the CHIPDeviceController. This call must happen
208 : * asynchronously, after ThreadCredentialsNeeded has returned.
209 : *
210 : * @param[in] endpoint the endpoint that hosts the Network Commissioning cluster the credentials are needed for.
211 : */
212 0 : virtual CHIP_ERROR ThreadCredentialsNeeded(EndpointId endpoint) { return CHIP_ERROR_NOT_IMPLEMENTED; }
213 : };
214 :
215 : } // namespace Controller
216 : } // namespace chip
|
