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 <stdint.h>
27 :
28 : #include <optional>
29 :
30 : namespace chip {
31 : namespace Controller {
32 :
33 : /**
34 : * A delegate that can be notified of progress as a "pairing" (which might mean
35 : * "PASE session establishment" or "commissioning") proceeds.
36 : */
37 : class DLL_EXPORT DevicePairingDelegate
38 : {
39 : public:
40 0 : virtual ~DevicePairingDelegate() {}
41 :
42 : enum Status : uint8_t
43 : {
44 : SecurePairingSuccess = 0,
45 : SecurePairingFailed,
46 : };
47 :
48 : /**
49 : * @brief
50 : * Called when the pairing reaches a certain stage.
51 : *
52 : * @param status Current status of pairing
53 : */
54 0 : virtual void OnStatusUpdate(DevicePairingDelegate::Status status) {}
55 :
56 : /**
57 : * @brief
58 : * Called when PASE session establishment is complete (with success or error)
59 : *
60 : * @param error Error cause, if any
61 : */
62 0 : virtual void OnPairingComplete(CHIP_ERROR error) {}
63 :
64 : /**
65 : * @brief
66 : * Called when PASE session establishment is complete (with success or error)
67 : *
68 : * @param error Error cause, if any
69 : *
70 : * @param rendezvousParameters The RendezvousParameters that were used for PASE establishment.
71 : * If available, this helps identify which exact commissionee PASE
72 : * was established for. This will generally be present only when
73 : * PASE establishment succeeds.
74 : */
75 0 : virtual void OnPairingComplete(CHIP_ERROR error, const std::optional<RendezvousParameters> & rendezvousParameters)
76 : {
77 0 : OnPairingComplete(error);
78 0 : }
79 :
80 : /**
81 : * @brief
82 : * Called when the pairing is deleted (with success or error)
83 : *
84 : * @param error Error cause, if any
85 : */
86 0 : virtual void OnPairingDeleted(CHIP_ERROR error) {}
87 :
88 : /**
89 : * Called when the commissioning process is complete (with success or error)
90 : */
91 0 : virtual void OnCommissioningComplete(NodeId deviceId, CHIP_ERROR error) {}
92 0 : virtual void OnCommissioningSuccess(PeerId peerId) {}
93 0 : virtual void OnCommissioningFailure(PeerId peerId, CHIP_ERROR error, CommissioningStage stageFailed,
94 : Optional<Credentials::AttestationVerificationResult> additionalErrorInfo)
95 0 : {}
96 :
97 0 : virtual void OnCommissioningStatusUpdate(PeerId peerId, CommissioningStage stageCompleted, CHIP_ERROR error) {}
98 :
99 : /**
100 : * @brief
101 : * Called with the ReadCommissioningInfo returned from the target
102 : */
103 0 : virtual void OnReadCommissioningInfo(const ReadCommissioningInfo & info) {}
104 :
105 : /**
106 : * @brief
107 : * Called when MatchingFabricInfo returned from target
108 : */
109 0 : virtual void OnFabricCheck(NodeId matchingNodeId) {}
110 :
111 : /**
112 : * @brief
113 : * Called with the NetworkScanResponse returned from the target.
114 : *
115 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
116 : *
117 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
118 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
119 : * in order to resume the commissioning process.
120 : */
121 : virtual void
122 0 : OnScanNetworksSuccess(const app::Clusters::NetworkCommissioning::Commands::ScanNetworksResponse::DecodableType & dataResponse)
123 0 : {}
124 :
125 : /**
126 : * @brief
127 : * Called when the NetworkScan request fails.
128 : *
129 : * The DeviceCommissioner will be waiting in the kNeedsNetworkCreds step and not advancing the commissioning process.
130 : *
131 : * The implementation should set the network credentials on the CommissioningParameters of the CommissioningDelegate
132 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.NetworkCredentialsReady()
133 : * in order to resume the commissioning process.
134 : */
135 0 : virtual void OnScanNetworksFailure(CHIP_ERROR error) {}
136 :
137 : /**
138 : * @brief
139 : * Called when the ICD registration information (ICD symmetric key, check-in node ID and monitored subject) is required.
140 : *
141 : * The DeviceCommissioner will be waiting in the kICDGetRegistrationInfo step and not advancing the commissioning process.
142 : *
143 : * The implementation should set the ICD registration info on the CommissioningParameters of the CommissioningDelegate
144 : * using CommissioningDelegate.SetCommissioningParameters(), and then call DeviceCommissioner.ICDRegistrationInfoReady()
145 : * in order to resume the commissioning process.
146 : *
147 : * Not called if the ICD registration info is provided up front.
148 : */
149 0 : virtual void OnICDRegistrationInfoRequired() {}
150 :
151 : /**
152 : * @brief
153 : * Called when the registration flow for the ICD completes.
154 : *
155 : * @param[in] icdNodeId The node id of the ICD.
156 : * @param[in] icdCounter The ICD Counter received from the device.
157 : */
158 0 : virtual void OnICDRegistrationComplete(ScopedNodeId icdNodeId, uint32_t icdCounter) {}
159 :
160 : /**
161 : * @brief
162 : * Called upon completion of the LIT ICD commissioning flow, when ICDStayActiveDuration is set
163 : * and the corresponding stayActive command response is received
164 : *
165 : * @param[in] icdNodeId The node id of the ICD.
166 : * @param[in] promisedActiveDurationMsec The actual duration that the ICD server can stay active
167 : * from the time it receives the StayActiveRequest command.
168 : */
169 0 : virtual void OnICDStayActiveComplete(ScopedNodeId icdNodeId, uint32_t promisedActiveDurationMsec) {}
170 :
171 : /**
172 : * @brief
173 : * Called when a commissioning stage starts.
174 : *
175 : * @param[in] peerId an identifier for the commissioning process. This is generally the
176 : * client-provided commissioning identifier before AddNOC and the actual
177 : * NodeID of the node after AddNoc, combined with the compressed fabric ID for
178 : * the fabric doing the commissioning.
179 : * @param[in] stageStarting the stage being started.
180 : */
181 0 : virtual void OnCommissioningStageStart(PeerId peerId, CommissioningStage stageStarting) {}
182 : };
183 :
184 : } // namespace Controller
185 : } // namespace chip
|
