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 : ~TransferFacilitator() override;
49 :
50 : /**
51 : * Calls reset on the TransferSession object and stops the poll timer.
52 : */
53 : void ResetTransfer();
54 :
55 : private:
56 : //// UnsolicitedMessageHandler Implementation ////
57 0 : CHIP_ERROR OnUnsolicitedMessageReceived(const PayloadHeader & payloadHeader, ExchangeDelegate *& newDelegate) override
58 : {
59 : // TODO: Implement a bdx manager, which dispatch bdx messages to bdx transections.
60 : // directly.
61 0 : newDelegate = this;
62 0 : return CHIP_NO_ERROR;
63 : }
64 :
65 : // Inherited from ExchangeContext
66 : void OnResponseTimeout(Messaging::ExchangeContext * ec) override;
67 :
68 : /**
69 : * This method should be implemented to contain business-logic handling of BDX messages and other TransferSession events.
70 : *
71 : * NOTE: It is the responsiblity of the implementer to Close the underlying ExchangeContext when it has determined that the
72 : * transfer is finished. This class assumes that a response message will be sent for all received messages.
73 : *
74 : * @param[in] event An OutputEvent that contains output from the TransferSession object.
75 : */
76 : virtual void HandleTransferSessionOutput(TransferSession::OutputEvent & event) = 0;
77 :
78 : protected:
79 : // Inherited from ExchangeContext
80 : CHIP_ERROR OnMessageReceived(chip::Messaging::ExchangeContext * ec, const chip::PayloadHeader & payloadHeader,
81 : chip::System::PacketBufferHandle && payload) override;
82 :
83 : /**
84 : * The callback for when the poll timer expires. The poll timer regulates how often the TransferSession is polled.
85 : */
86 : static void PollTimerHandler(chip::System::Layer * systemLayer, void * appState);
87 :
88 : /**
89 : * Polls the TransferSession object and calls HandleTransferSessionOutput.
90 : */
91 : void PollForOutput();
92 :
93 : /**
94 : * Starts the poll timer with a very short timeout.
95 : */
96 : void ScheduleImmediatePoll();
97 :
98 : TransferSession mTransfer;
99 : Messaging::ExchangeContext * mExchangeCtx = nullptr;
100 : System::Layer * mSystemLayer = nullptr;
101 : System::Clock::Timeout mPollFreq;
102 : static constexpr System::Clock::Timeout kDefaultPollFreq = System::Clock::Milliseconds32(500);
103 : static constexpr System::Clock::Timeout kImmediatePollDelay = System::Clock::Milliseconds32(1);
104 : };
105 :
106 : /**
107 : * A TransferFacilitator that is initialized to respond to an incoming BDX transfer request.
108 : *
109 : * Provides a method for initializing the TransferSession member but still needs to be extended to implement
110 : * HandleTransferSessionOutput. It is intended that this class will be used as a delegate for handling an unsolicited BDX message.
111 : */
112 : class Responder : public TransferFacilitator
113 : {
114 : public:
115 : /**
116 : * Initialize the TransferSession state machine to be ready for an incoming transfer request, and start the polling timer.
117 : *
118 : * @param[in] layer A System::Layer pointer to use to start the polling timer
119 : * @param[in] role The role of the Responder: Sender or Receiver of BDX data
120 : * @param[in] xferControlOpts Supported transfer modes (see TransferControlFlags)
121 : * @param[in] maxBlockSize The supported maximum size of BDX Block data
122 : * @param[in] timeout The chosen timeout delay for the BDX transfer
123 : * @param[in] pollFreq The period for the TransferSession poll timer
124 : */
125 : CHIP_ERROR PrepareForTransfer(System::Layer * layer, TransferRole role, BitFlags<TransferControlFlags> xferControlOpts,
126 : uint16_t maxBlockSize, System::Clock::Timeout timeout,
127 : System::Clock::Timeout pollFreq = TransferFacilitator::kDefaultPollFreq);
128 : };
129 :
130 : /**
131 : * A TransferFacilitator that initiates a BDX transfer.
132 : *
133 : * Provides a method for initializing the TransferSession member (thus beginning the transfer) but still needs to be extended to
134 : * implement HandleTransferSessionOutput.
135 : */
136 : class Initiator : public TransferFacilitator
137 : {
138 : public:
139 : /**
140 : * Initialize the TransferSession state machine to prepare a transfer request message (does not send the message) and start the
141 : * poll timer.
142 : *
143 : * @param[in] layer A System::Layer pointer to use to start the polling timer
144 : * @param[in] role The role of the Initiator: Sender or Receiver of BDX data
145 : * @param[in] initData Data needed for preparing a transfer request BDX message
146 : * @param[in] timeout The chosen timeout delay for the BDX transfer in milliseconds
147 : * @param[in] pollFreq The period for the TransferSession poll timer in milliseconds
148 : */
149 : CHIP_ERROR InitiateTransfer(System::Layer * layer, TransferRole role, const TransferSession::TransferInitData & initData,
150 : System::Clock::Timeout timeout,
151 : System::Clock::Timeout pollFreq = TransferFacilitator::kDefaultPollFreq);
152 : };
153 :
154 : } // namespace bdx
155 : } // namespace chip
|
