Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2021 Project CHIP Authors
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : /**
      19             :  * @file BdxEndpoint.h
      20             :  *
      21             :  *  This file defines interfaces for connecting the BDX state machine (TransferSession) to the messaging layer.
      22             :  */
      23             : 
      24             : #include <lib/core/CHIPError.h>
      25             : #include <lib/support/BitFlags.h>
      26             : #include <messaging/ExchangeContext.h>
      27             : #include <messaging/ExchangeDelegate.h>
      28             : #include <protocols/bdx/BdxTransferSession.h>
      29             : #include <system/SystemLayer.h>
      30             : 
      31             : #pragma once
      32             : 
      33             : namespace chip {
      34             : namespace bdx {
      35             : 
      36             : /**
      37             :  * An abstract class with methods for handling BDX messages from an ExchangeContext and polling a TransferSession state machine.
      38             :  *
      39             :  * This class does not define any methods for beginning a transfer or initializing the underlying TransferSession object (see
      40             :  * Initiator and Responder below).
      41             :  * This class contains a repeating timer which regurlaly polls the TransferSession state machine.
      42             :  * A CHIP node may have many TransferFacilitator instances but only one TransferFacilitator should be used for each BDX transfer.
      43             :  */
      44             : class TransferFacilitator : public Messaging::ExchangeDelegate, public Messaging::UnsolicitedMessageHandler
      45             : {
      46             : public:
      47           0 :     TransferFacilitator() : mExchangeCtx(nullptr), mSystemLayer(nullptr), mPollFreq(kDefaultPollFreq) {}
      48           0 :     ~TransferFacilitator() override = default;
      49             : 
      50             : private:
      51             :     //// UnsolicitedMessageHandler Implementation ////
      52           0 :     CHIP_ERROR OnUnsolicitedMessageReceived(const PayloadHeader & payloadHeader, ExchangeDelegate *& newDelegate) override
      53             :     {
      54             :         // TODO: Implement a bdx manager, which dispatch bdx messages to bdx transections.
      55             :         // directly.
      56           0 :         newDelegate = this;
      57           0 :         return CHIP_NO_ERROR;
      58             :     }
      59             : 
      60             :     // Inherited from ExchangeContext
      61             :     void OnResponseTimeout(Messaging::ExchangeContext * ec) override;
      62             : 
      63             :     /**
      64             :      * This method should be implemented to contain business-logic handling of BDX messages and other TransferSession events.
      65             :      *
      66             :      * NOTE: It is the responsiblity of the implementer to Close the underlying ExchangeContext when it has determined that the
      67             :      * transfer is finished. This class assumes that a response message will be sent for all received messages.
      68             :      *
      69             :      * @param[in] event An OutputEvent that contains output from the TransferSession object.
      70             :      */
      71             :     virtual void HandleTransferSessionOutput(TransferSession::OutputEvent & event) = 0;
      72             : 
      73             : protected:
      74             :     // Inherited from ExchangeContext
      75             :     CHIP_ERROR OnMessageReceived(chip::Messaging::ExchangeContext * ec, const chip::PayloadHeader & payloadHeader,
      76             :                                  chip::System::PacketBufferHandle && payload) override;
      77             : 
      78             :     /**
      79             :      * The callback for when the poll timer expires. The poll timer regulates how often the TransferSession is polled.
      80             :      */
      81             :     static void PollTimerHandler(chip::System::Layer * systemLayer, void * appState);
      82             : 
      83             :     /**
      84             :      * Polls the TransferSession object and calls HandleTransferSessionOutput.
      85             :      */
      86             :     void PollForOutput();
      87             : 
      88             :     /**
      89             :      * Starts the poll timer with a very short timeout.
      90             :      */
      91             :     void ScheduleImmediatePoll();
      92             : 
      93             :     TransferSession mTransfer;
      94             :     Messaging::ExchangeContext * mExchangeCtx;
      95             :     System::Layer * mSystemLayer;
      96             :     System::Clock::Timeout mPollFreq;
      97             :     static constexpr System::Clock::Timeout kDefaultPollFreq    = System::Clock::Milliseconds32(500);
      98             :     static constexpr System::Clock::Timeout kImmediatePollDelay = System::Clock::Milliseconds32(1);
      99             :     bool mStopPolling                                           = false;
     100             : };
     101             : 
     102             : /**
     103             :  * A TransferFacilitator that is initialized to respond to an incoming BDX transfer request.
     104             :  *
     105             :  * Provides a method for initializing the TransferSession member but still needs to be extended to implement
     106             :  * HandleTransferSessionOutput. It is intended that this class will be used as a delegate for handling an unsolicited BDX message.
     107             :  */
     108             : class Responder : public TransferFacilitator
     109             : {
     110             : public:
     111             :     /**
     112             :      * Initialize the TransferSession state machine to be ready for an incoming transfer request, and start the polling timer.
     113             :      *
     114             :      * @param[in] layer           A System::Layer pointer to use to start the polling timer
     115             :      * @param[in] role            The role of the Responder: Sender or Receiver of BDX data
     116             :      * @param[in] xferControlOpts Supported transfer modes (see TransferControlFlags)
     117             :      * @param[in] maxBlockSize    The supported maximum size of BDX Block data
     118             :      * @param[in] timeout         The chosen timeout delay for the BDX transfer
     119             :      * @param[in] pollFreq        The period for the TransferSession poll timer
     120             :      */
     121             :     CHIP_ERROR PrepareForTransfer(System::Layer * layer, TransferRole role, BitFlags<TransferControlFlags> xferControlOpts,
     122             :                                   uint16_t maxBlockSize, System::Clock::Timeout timeout,
     123             :                                   System::Clock::Timeout pollFreq = TransferFacilitator::kDefaultPollFreq);
     124             : 
     125             :     /**
     126             :      * Calls reset on the TransferSession object and stops the poll timer.
     127             :      */
     128             :     void ResetTransfer();
     129             : };
     130             : 
     131             : /**
     132             :  * A TransferFacilitator that initiates a BDX transfer.
     133             :  *
     134             :  * Provides a method for initializing the TransferSession member (thus beginning the transfer) but still needs to be extended to
     135             :  * implement HandleTransferSessionOutput.
     136             :  */
     137             : class Initiator : public TransferFacilitator
     138             : {
     139             : public:
     140             :     /**
     141             :      * Initialize the TransferSession state machine to prepare a transfer request message (does not send the message) and start the
     142             :      * poll timer.
     143             :      *
     144             :      * @param[in] layer      A System::Layer pointer to use to start the polling timer
     145             :      * @param[in] role       The role of the Initiator: Sender or Receiver of BDX data
     146             :      * @param[in] initData   Data needed for preparing a transfer request BDX message
     147             :      * @param[in] timeout    The chosen timeout delay for the BDX transfer in milliseconds
     148             :      * @param[in] pollFreq   The period for the TransferSession poll timer in milliseconds
     149             :      */
     150             :     CHIP_ERROR InitiateTransfer(System::Layer * layer, TransferRole role, const TransferSession::TransferInitData & initData,
     151             :                                 System::Clock::Timeout timeout,
     152             :                                 System::Clock::Timeout pollFreq = TransferFacilitator::kDefaultPollFreq);
     153             :     /**
     154             :      * Calls reset on the TransferSession object and stops the poll timer.
     155             :      */
     156             :     void ResetTransfer();
     157             : };
     158             : 
     159             : } // namespace bdx
     160             : } // namespace chip