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