Matter SDK Coverage Report
Current view: top level - controller - DevicePairingDelegate.h (source / functions) Coverage Total Hit
Test: SHA:3108862db59e5fa02f4a254cea1d5089c60155eb Lines: 0.0 % 23 0
Test Date: 2025-10-12 07:08:15 Functions: 0.0 % 20 0

            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
        

Generated by: LCOV version 2.0-1