Matter SDK Coverage Report
Current view: top level - app - CASESessionManager.h (source / functions) Coverage Total Hit
Test: SHA:4cbce7f768f16e614f5a8ccb8cd93c92cbeae70d Lines: 100.0 % 6 6
Test Date: 2025-04-26 07:09:35 Functions: 66.7 % 3 2

            Line data    Source code
       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2020-2021 Project CHIP Authors
       4              :  *    All rights reserved.
       5              :  *
       6              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7              :  *    you may not use this file except in compliance with the License.
       8              :  *    You may obtain a copy of the License at
       9              :  *
      10              :  *        http://www.apache.org/licenses/LICENSE-2.0
      11              :  *
      12              :  *    Unless required by applicable law or agreed to in writing, software
      13              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15              :  *    See the License for the specific language governing permissions and
      16              :  *    limitations under the License.
      17              :  */
      18              : 
      19              : #pragma once
      20              : 
      21              : #include <app/CASEClientPool.h>
      22              : #include <app/OperationalSessionSetup.h>
      23              : #include <app/OperationalSessionSetupPool.h>
      24              : #include <lib/core/CHIPConfig.h>
      25              : #include <lib/core/CHIPCore.h>
      26              : #include <lib/support/Pool.h>
      27              : #include <platform/CHIPDeviceLayer.h>
      28              : #include <transport/SessionDelegate.h>
      29              : #include <transport/SessionManager.h>
      30              : #include <transport/SessionUpdateDelegate.h>
      31              : 
      32              : namespace chip {
      33              : 
      34              : struct CASESessionManagerConfig
      35              : {
      36              :     CASEClientInitParams sessionInitParams;
      37              :     CASEClientPoolDelegate * clientPool                    = nullptr;
      38              :     OperationalSessionSetupPoolDelegate * sessionSetupPool = nullptr;
      39              : };
      40              : 
      41              : /**
      42              :  * This class provides the following
      43              :  * 1. Manage a pool of operational device proxy objects for peer nodes that have active message exchange with the local node.
      44              :  * 2. The pool contains atmost one device proxy object for a given peer node.
      45              :  * 3. API to lookup an existing proxy object, or allocate a new one by triggering session establishment with the peer node.
      46              :  * 4. During session establishment, trigger node ID resolution (if needed), and update the DNS-SD cache (if resolution is
      47              :  * successful)
      48              :  */
      49              : class CASESessionManager : public OperationalSessionReleaseDelegate, public SessionUpdateDelegate
      50              : {
      51              : public:
      52            2 :     CASESessionManager() = default;
      53            2 :     virtual ~CASESessionManager()
      54            2 :     {
      55            2 :         if (mConfig.sessionInitParams.Validate() == CHIP_NO_ERROR)
      56              :         {
      57            1 :             mConfig.sessionInitParams.exchangeMgr->GetReliableMessageMgr()->RegisterSessionUpdateDelegate(nullptr);
      58              :         }
      59            2 :     }
      60              : 
      61              :     CHIP_ERROR Init(chip::System::Layer * systemLayer, const CASESessionManagerConfig & params);
      62              :     void Shutdown();
      63              : 
      64              :     /**
      65              :      * Find an existing session for the given node ID, or trigger a new session
      66              :      * request.
      67              :      *
      68              :      * The caller can optionally provide `onConnection` and `onFailure` callback
      69              :      * objects. If provided, these will be used to inform the caller about
      70              :      * successful or failed connection establishment.
      71              :      *
      72              :      * If the connection is already established, the `onConnection` callback
      73              :      * will be immediately called, before FindOrEstablishSession returns.
      74              :      *
      75              :      * The `onFailure` callback may be called before the FindOrEstablishSession
      76              :      * call returns, for error cases that are detected synchronously.
      77              :      *
      78              :      * attemptCount can be set to a value greater than 1 to automatically make at least
      79              :      * attemptCount session establishment attempts until session setup is successful.
      80              :      */
      81              :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
      82              :                                 Callback::Callback<OnDeviceConnectionFailure> * onFailure,
      83              : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
      84              :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
      85              : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
      86              :                                 TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
      87              : 
      88              :     /**
      89              :      * Find an existing session for the given node ID or trigger a new session request.
      90              :      *
      91              :      * The caller can optionally provide `onConnection` and `onSetupFailure`
      92              :      * callback objects. If provided, these will be used to inform the caller about successful or
      93              :      * failed connection establishment.
      94              :      *
      95              :      * If the connection is already established, the `onConnection` callback will be immediately called,
      96              :      * before `FindOrEstablishSession` returns.
      97              :      *
      98              :      * The `onSetupFailure` callback may be called before the `FindOrEstablishSession`
      99              :      * call returns, for error cases that are detected synchronously.
     100              :      *
     101              :      * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
     102              :      * at least attemptCount session establishment attempts until session setup is successful.
     103              :      *
     104              :      * @param peerId The node ID to find or establish a session with.
     105              :      * @param onConnection A callback to be called upon successful connection establishment.
     106              :      * @param onSetupFailure A callback to be called upon an extended device connection failure.
     107              :      * @param attemptCount The number of attempts to make at establishing a session.  If set to a number larger than 1,
     108              :      *                     a session setup failure will lead to a retry, with at least attemptCount total attempts.
     109              :      * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     110              :      * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     111              :      */
     112              :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
     113              :                                 Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
     114              : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     115              :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
     116              : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     117              :                                 TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
     118              : 
     119              :     /**
     120              :      * Find an existing session for the given node ID or trigger a new session request.
     121              :      *
     122              :      * The caller can optionally provide `onConnection`
     123              :      * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
     124              :      *
     125              :      * If the connection is already established, the `onConnection` callback will be immediately called,
     126              :      * before `FindOrEstablishSession` returns.
     127              :      *
     128              :      * The `attemptCount` parameter can be set to a value greater than 1 to automatically make
     129              :      * at least attemptCount session establishment attempts until session setup is successful.
     130              :      *
     131              :      * This function allows passing 'nullptr' for the error handler to compile, which is useful in scenarios where error
     132              :      * handling is not needed.
     133              :      *
     134              :      * @param peerId The node ID to find or establish a session with.
     135              :      * @param onConnection A callback to be called upon successful connection establishment.
     136              :      * @param attemptCount The number of attempts to make at establishing a session.  If set to a number larger than 1,
     137              :      *                     a session setup failure will lead to a retry, with at least attemptCount total attempts.
     138              :      * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     139              :      * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     140              :      */
     141              :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection, std::nullptr_t,
     142              : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     143              :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr,
     144              : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     145              :                                 TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
     146              : 
     147              :     /**
     148              :      * Find an existing session for the given node ID or trigger a new session request.
     149              :      *
     150              :      * The caller can optionally provide `onConnection`
     151              :      * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
     152              :      *
     153              :      * If the connection is already established, the `onConnection` callback will be immediately called,
     154              :      * before `FindOrEstablishSession` returns.
     155              :      *
     156              :      * The `onFailure` callback may be called before the FindOrEstablishSession
     157              :      * call returns, for error cases that are detected synchronously.
     158              :      *
     159              :      * @note This API uses default values for automatic CASE retries, if enabled.
     160              :      *
     161              :      * @param peerId The node ID to find or establish a session with.
     162              :      * @param onConnection A callback to be called upon successful connection establishment.
     163              :      * @param onSetupFailure A callback to be called upon an extended device connection failure.
     164              :      * @param transportPayloadCapability An indicator of what payload types the session needs to be able to transport.
     165              :      */
     166              :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
     167              :                                 Callback::Callback<OnDeviceConnectionFailure> * onFailure,
     168              :                                 TransportPayloadCapability transportPayloadCapability);
     169              : 
     170              :     void ReleaseSession(const ScopedNodeId & peerId);
     171              :     void ReleaseSessionsForFabric(FabricIndex fabricIndex);
     172              : 
     173              :     void ReleaseAllSessions();
     174              : 
     175              :     /**
     176              :      * This API returns the address for the given node ID.
     177              :      * If the CASESessionManager is configured with a DNS-SD cache, the cache is looked up
     178              :      * for the node ID.
     179              :      * If the DNS-SD cache is not available, the CASESessionManager looks up the list for
     180              :      * an ongoing session with the peer node. If the session doesn't exist, the API will return
     181              :      * `CHIP_ERROR_NOT_CONNECTED` error.
     182              :      */
     183              :     CHIP_ERROR GetPeerAddress(const ScopedNodeId & peerId, Transport::PeerAddress & addr,
     184              :                               TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload);
     185              : 
     186              :     //////////// OperationalSessionReleaseDelegate Implementation ///////////////
     187              :     void ReleaseSession(OperationalSessionSetup * device) override;
     188              : 
     189              :     //////////// SessionUpdateDelegate Implementation ///////////////
     190              :     void UpdatePeerAddress(ScopedNodeId peerId) override;
     191              : 
     192              : private:
     193              :     OperationalSessionSetup * FindExistingSessionSetup(const ScopedNodeId & peerId, bool forAddressUpdate = false) const;
     194              : 
     195              :     Optional<SessionHandle> FindExistingSession(
     196              :         const ScopedNodeId & peerId,
     197              :         const TransportPayloadCapability transportPayloadCapability = TransportPayloadCapability::kMRPPayload) const;
     198              : 
     199              :     void FindOrEstablishSessionHelper(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
     200              :                                       Callback::Callback<OnDeviceConnectionFailure> * onFailure,
     201              :                                       Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
     202              : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     203              :                                       uint8_t attemptCount, Callback::Callback<OnDeviceConnectionRetry> * onRetry,
     204              : #endif
     205              :                                       TransportPayloadCapability transportPayloadCapability);
     206              : 
     207              :     CASESessionManagerConfig mConfig;
     208              : };
     209              : 
     210              : } // namespace chip
        

Generated by: LCOV version 2.0-1