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/SessionUpdateDelegate.h>
      30             : 
      31             : namespace chip {
      32             : 
      33             : class OperationalSessionSetupPoolDelegate;
      34             : 
      35             : struct CASESessionManagerConfig
      36             : {
      37             :     CASEClientInitParams sessionInitParams;
      38             :     CASEClientPoolDelegate * clientPool                    = nullptr;
      39             :     OperationalSessionSetupPoolDelegate * sessionSetupPool = nullptr;
      40             : };
      41             : 
      42             : /**
      43             :  * This class provides the following
      44             :  * 1. Manage a pool of operational device proxy objects for peer nodes that have active message exchange with the local node.
      45             :  * 2. The pool contains atmost one device proxy object for a given peer node.
      46             :  * 3. API to lookup an existing proxy object, or allocate a new one by triggering session establishment with the peer node.
      47             :  * 4. During session establishment, trigger node ID resolution (if needed), and update the DNS-SD cache (if resolution is
      48             :  * successful)
      49             :  */
      50             : class CASESessionManager : public OperationalSessionReleaseDelegate, public SessionUpdateDelegate
      51             : {
      52             : public:
      53           1 :     CASESessionManager() = default;
      54           1 :     virtual ~CASESessionManager()
      55           1 :     {
      56           1 :         if (mConfig.sessionInitParams.Validate() == CHIP_NO_ERROR)
      57             :         {
      58           1 :             mConfig.sessionInitParams.exchangeMgr->GetReliableMessageMgr()->RegisterSessionUpdateDelegate(nullptr);
      59             :         }
      60           1 :     }
      61             : 
      62             :     CHIP_ERROR Init(chip::System::Layer * systemLayer, const CASESessionManagerConfig & params);
      63           1 :     void Shutdown() {}
      64             : 
      65             :     /**
      66             :      * Find an existing session for the given node ID, or trigger a new session
      67             :      * request.
      68             :      *
      69             :      * The caller can optionally provide `onConnection` and `onFailure` callback
      70             :      * objects. If provided, these will be used to inform the caller about
      71             :      * successful or failed connection establishment.
      72             :      *
      73             :      * If the connection is already established, the `onConnection` callback
      74             :      * will be immediately called, before FindOrEstablishSession returns.
      75             :      *
      76             :      * The `onFailure` callback may be called before the FindOrEstablishSession
      77             :      * call returns, for error cases that are detected synchronously.
      78             :      *
      79             :      * attemptCount can be used to automatically retry multiple times if session
      80             :      * setup is not successful.
      81             :      */
      82             :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
      83             :                                 Callback::Callback<OnDeviceConnectionFailure> * onFailure
      84             : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
      85             :                                 ,
      86             :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr
      87             : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
      88             :     );
      89             : 
      90             :     /**
      91             :      * Find an existing session for the given node ID or trigger a new session request.
      92             :      *
      93             :      * The caller can optionally provide `onConnection` and `onSetupFailure`
      94             :      * callback objects. If provided, these will be used to inform the caller about successful or
      95             :      * failed connection establishment.
      96             :      *
      97             :      * If the connection is already established, the `onConnection` callback will be immediately called,
      98             :      * before `FindOrEstablishSession` returns.
      99             :      *
     100             :      * The `onSetupFailure` callback may be called before the `FindOrEstablishSession`
     101             :      * call returns, for error cases that are detected synchronously.
     102             :      *
     103             :      * The `attemptCount` parameter can be used to automatically retry multiple times if session setup is
     104             :      * not successful.
     105             :      *
     106             :      * @param peerId The node ID to find or establish a session with.
     107             :      * @param onConnection A callback to be called upon successful connection establishment.
     108             :      * @param onSetupFailure A callback to be called upon an extended device connection failure.
     109             :      * @param attemptCount The number of retry attempts if session setup fails (default is 1).
     110             :      * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     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             :                                 ,
     116             :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr
     117             : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     118             :     );
     119             : 
     120             :     /**
     121             :      * Find an existing session for the given node ID or trigger a new session request.
     122             :      *
     123             :      * The caller can optionally provide `onConnection`
     124             :      * callback objects. If provided, these will be used to inform the caller about successful connection establishment.
     125             :      *
     126             :      * If the connection is already established, the `onConnection` callback will be immediately called,
     127             :      * before `FindOrEstablishSession` returns.
     128             :      *
     129             :      * The `attemptCount` parameter can be used to automatically retry multiple times if session setup is
     130             :      * not successful.
     131             :      *
     132             :      * This function allows passing 'nullptr' for the error handler to compile, which is useful in scenarios where error
     133             :      * handling is not needed.
     134             :      *
     135             :      * @param peerId The node ID to find or establish a session with.
     136             :      * @param onConnection A callback to be called upon successful connection establishment.
     137             :      * @param attemptCount The number of retry attempts if session setup fails (default is 1).
     138             :      * @param onRetry A callback to be called on a retry attempt (enabled by a config flag).
     139             :      */
     140             :     void FindOrEstablishSession(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection, nullptr_t
     141             : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     142             :                                 ,
     143             :                                 uint8_t attemptCount = 1, Callback::Callback<OnDeviceConnectionRetry> * onRetry = nullptr
     144             : #endif // CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     145             :     );
     146             : 
     147             :     void ReleaseSessionsForFabric(FabricIndex fabricIndex);
     148             : 
     149             :     void ReleaseAllSessions();
     150             : 
     151             :     /**
     152             :      * This API returns the address for the given node ID.
     153             :      * If the CASESessionManager is configured with a DNS-SD cache, the cache is looked up
     154             :      * for the node ID.
     155             :      * If the DNS-SD cache is not available, the CASESessionManager looks up the list for
     156             :      * an ongoing session with the peer node. If the session doesn't exist, the API will return
     157             :      * `CHIP_ERROR_NOT_CONNECTED` error.
     158             :      */
     159             :     CHIP_ERROR GetPeerAddress(const ScopedNodeId & peerId, Transport::PeerAddress & addr);
     160             : 
     161             :     //////////// OperationalSessionReleaseDelegate Implementation ///////////////
     162             :     void ReleaseSession(OperationalSessionSetup * device) override;
     163             : 
     164             :     //////////// SessionUpdateDelegate Implementation ///////////////
     165             :     void UpdatePeerAddress(ScopedNodeId peerId) override;
     166             : 
     167             : private:
     168             :     OperationalSessionSetup * FindExistingSessionSetup(const ScopedNodeId & peerId, bool forAddressUpdate = false) const;
     169             : 
     170             :     Optional<SessionHandle> FindExistingSession(const ScopedNodeId & peerId) const;
     171             : 
     172             :     void FindOrEstablishSessionHelper(const ScopedNodeId & peerId, Callback::Callback<OnDeviceConnected> * onConnection,
     173             :                                       Callback::Callback<OnDeviceConnectionFailure> * onFailure,
     174             :                                       Callback::Callback<OperationalSessionSetup::OnSetupFailure> * onSetupFailure,
     175             : #if CHIP_DEVICE_CONFIG_ENABLE_AUTOMATIC_CASE_RETRIES
     176             :                                       uint8_t attemptCount, Callback::Callback<OnDeviceConnectionRetry> * onRetry
     177             : #endif
     178             :     );
     179             : 
     180             :     CASESessionManagerConfig mConfig;
     181             : };
     182             : 
     183             : } // namespace chip