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              : class DLL_EXPORT SessionDelegate
      27              : {
      28              : public:
      29         3480 :     virtual ~SessionDelegate() {}
      30              : 
      31              :     enum class NewSessionHandlingPolicy : uint8_t
      32              :     {
      33              :         kShiftToNewSession,
      34              :         kStayAtOldSession,
      35              :     };
      36              : 
      37              :     /**
      38              :      * @brief
      39              :      *   Called when a new secure session to the same peer is established, over the delegate of SessionHolderWithDelegate object. It
      40              :      *   is suggested to shift to the newly created session.
      41              :      *
      42              :      *   Our security model is built upon Exchanges and Sessions, but not SessionHolders, such that SessionHolders should be able to
      43              :      *   shift to a new session freely. If an application is holding a session which is not intended to be shifted, it can provide
      44              :      *   its shifting policy by overriding GetNewSessionHandlingPolicy in SessionDelegate. For example SessionHolders inside
      45              :      *   ExchangeContext and PairingSession are not eligible for auto-shifting.
      46              :      *
      47              :      * Note: the default implementation orders shifting to the new session, it should be fine for all users, unless the
      48              :      *       SessionHolder object is expected to be sticky to a specified session.
      49              :      *
      50              :      * Note: the implementation MUST NOT modify the session pool or the state of session holders (eg, adding new session, removing
      51              :      *       old session) from inside this callback.
      52              :      */
      53            0 :     virtual NewSessionHandlingPolicy GetNewSessionHandlingPolicy() { return NewSessionHandlingPolicy::kShiftToNewSession; }
      54              : 
      55              :     /**
      56              :      * @brief
      57              :      *   Called when a session is releasing. Callees SHALL NOT make synchronous calls into SessionManager to allocate a new session.
      58              :      *   If they desire to do so, it MUST be done asynchronously.
      59              :      */
      60              :     virtual void OnSessionReleased() = 0;
      61              : 
      62              :     /**
      63              :      * @brief
      64              :      *   Called when a session is unresponsive for a while (detected by MRP). Callees SHALL NOT make synchronous calls into
      65              :      * SessionManager to allocate a new session. If they desire to do so, it MUST be done asynchronously.
      66              :      */
      67           11 :     virtual void OnSessionHang() {}
      68              : 
      69              : #if INET_CONFIG_ENABLE_TCP_ENDPOINT
      70            0 :     virtual void OnSessionConnectionClosed(CHIP_ERROR conErr) {}
      71              : #endif // INET_CONFIG_ENABLE_TCP_ENDPOINT
      72              : };
      73              : 
      74              : } // namespace chip