Line data    Source code

       1              : /*
       2              :  *    Copyright (c) 2021 Project CHIP Authors
       3              :  *
       4              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       5              :  *    you may not use this file except in compliance with the License.
       6              :  *    You may obtain a copy of the License at
       7              :  *
       8              :  *        http://www.apache.org/licenses/LICENSE-2.0
       9              :  *
      10              :  *    Unless required by applicable law or agreed to in writing, software
      11              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      12              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      13              :  *    See the License for the specific language governing permissions and
      14              :  *    limitations under the License.
      15              :  */
      16              : 
      17              : #pragma once
      18              : 
      19              : #include <inttypes.h>
      20              : 
      21              : #include <lib/core/CHIPError.h>
      22              : #include <lib/support/DLLUtil.h>
      23              : 
      24              : namespace chip {
      25              : 
      26              : namespace Transport {
      27              : class ActiveTCPConnectionHolder;
      28              : struct ActiveTCPConnectionState;
      29              : } // namespace Transport
      30              : 
      31              : class DLL_EXPORT SessionDelegate
      32              : {
      33              : public:
      34         4845 :     virtual ~SessionDelegate() {}
      35              : 
      36              :     enum class NewSessionHandlingPolicy : uint8_t
      37              :     {
      38              :         kShiftToNewSession,
      39              :         kStayAtOldSession,
      40              :     };
      41              : 
      42              :     /**
      43              :      * @brief
      44              :      *   Called when a new secure session to the same peer is established, over the delegate of SessionHolderWithDelegate object. It
      45              :      *   is suggested to shift to the newly created session.
      46              :      *
      47              :      *   Our security model is built upon Exchanges and Sessions, but not SessionHolders, such that SessionHolders should be able to
      48              :      *   shift to a new session freely. If an application is holding a session which is not intended to be shifted, it can provide
      49              :      *   its shifting policy by overriding GetNewSessionHandlingPolicy in SessionDelegate. For example SessionHolders inside
      50              :      *   ExchangeContext and PairingSession are not eligible for auto-shifting.
      51              :      *
      52              :      * Note: the default implementation orders shifting to the new session, it should be fine for all users, unless the
      53              :      *       SessionHolder object is expected to be sticky to a specified session.
      54              :      *
      55              :      * Note: the implementation MUST NOT modify the session pool or the state of session holders (eg, adding new session, removing
      56              :      *       old session) from inside this callback.
      57              :      */
      58            0 :     virtual NewSessionHandlingPolicy GetNewSessionHandlingPolicy() { return NewSessionHandlingPolicy::kShiftToNewSession; }
      59              : 
      60              :     /**
      61              :      * @brief
      62              :      *   Called when a session is releasing. Callees SHALL NOT make synchronous calls into SessionManager to allocate a new session.
      63              :      *   If they desire to do so, it MUST be done asynchronously.
      64              :      */
      65              :     virtual void OnSessionReleased() = 0;
      66              : 
      67              :     /**
      68              :      * @brief
      69              :      *   Called when a session is unresponsive for a while (detected by MRP). Callees SHALL NOT make synchronous calls into
      70              :      * SessionManager to allocate a new session. If they desire to do so, it MUST be done asynchronously.
      71              :      */
      72           16 :     virtual void OnSessionHang() {}
      73              : 
      74              : #if INET_CONFIG_ENABLE_TCP_ENDPOINT
      75            0 :     virtual void OnSessionConnectionClosed(const Transport::ActiveTCPConnectionState & conn, CHIP_ERROR connErr) {}
      76            0 :     virtual void OnConnectionAttemptComplete(Transport::ActiveTCPConnectionHolder & conn, CHIP_ERROR connErr) {}
      77              : #endif // INET_CONFIG_ENABLE_TCP_ENDPOINT
      78              : };
      79              : 
      80              : } // namespace chip