Add GetNextAction API so that a caller that might want to implement a… (

project-chip#35462)

* Add GetNextAction API so that a caller that might want to implement an event driven mechanism to drive the BDX transfer can get the next output event from the TransferSession on demand

Currently we have the PollOutput API where the expectation is the caller needs to poll frequently for the next output event from the TransferSession which introduces a delay based on the
poll interval in handling every single BDX message or transfer session event handled by the caller.

* Update src/protocols/bdx/BdxTransferSession.h

Co-authored-by: Boris Zbarsky <[email protected]>

* Address review comments

* Apply suggestions from code review

Co-authored-by: Boris Zbarsky <[email protected]>

* Restyled by clang-format

---------

Co-authored-by: Boris Zbarsky <[email protected]>
Co-authored-by: Restyled.io <[email protected]>

src/protocols/bdx/BdxTransferSession.cpp

@@ -134,6 +134,11 @@ void TransferSession::PollOutput(OutputEvent & event, System::Clock::Timestamp c
     mPendingOutput = OutputEventType::kNone;
 }
 
+void TransferSession::GetNextAction(OutputEvent & event)
+{
+    PollOutput(event, System::SystemClock().GetMonotonicTimestamp());
+}
+
 CHIP_ERROR TransferSession::StartTransfer(TransferRole role, const TransferInitData & initData, System::Clock::Timeout timeout)
 {
     VerifyOrReturnError(mState == TransferState::kUnitialized, CHIP_ERROR_INCORRECT_STATE);

src/protocols/bdx/BdxTransferSession.h

@@ -165,6 +165,25 @@ class DLL_EXPORT TransferSession
      */
     void PollOutput(OutputEvent & event, System::Clock::Timestamp curTime);
 
+    /**
+     * @brief
+     *   Gets the pending output event from the transfer session in the event param passed in by the caller.
+     *   The output event may contain some data for the caller to act upon. If there is no pending output event,
+     *   the caller will get an event of type OutputEventType::kNone.
+     *
+     *   It is possible that consecutive calls to this method may emit different outputs depending on the state of the
+     *   TransferSession object.  The caller is generally expected to keep calling this method until it gets an event of type
+     * OutputEventType::kNone.
+     *
+     *   If the output event type is kMsgToSend, the caller is expected to send the message immediately on the
+     *   relevant exchange.  In this case the BDX session timeout timer will start when GetNextAction is called.
+     *
+     *   See OutputEventType for all possible output event types.
+     *
+     * @param event     Reference to an OutputEvent struct that will be filled out with any pending output event data
+     */
+    void GetNextAction(OutputEvent & event);
+
     /**
      * @brief
      *   Initializes the TransferSession object and prepares a TransferInit message (emitted via PollOutput()).