From 0ac326ea570b78b400428b23bff68f81672de1a3 Mon Sep 17 00:00:00 2001
From: Abtin Keshavarzian <abtink@google.com>
Date: Thu, 24 Jan 2019 13:56:19 -0800
Subject: [PATCH] [mac] update "out of band tx" to check current operation
 state (#3461)

This commit changes the `SendOutOfBandFrameRequest()` implementation
to check `mOperation` and `mPending<>` state variables to determine
if MAC layer is still busy with a previous OOB tx request (instead of
using the `mOobFrame` pointer variable). This change makes the OOB tx
implementation behave similarly to other APIs (e.g., `ActiveScan()`
or `SendFrameRequest()`). This commit also enhances the documentation
for the OOB Send APIs in header files.
---
 include/openthread/link.h | 8 ++++++--
 src/core/mac/mac.cpp      | 6 +++---
 src/core/mac/mac.hpp      | 1 +
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/include/openthread/link.h b/include/openthread/link.h
index 9aa4bad54..ea4ea6042 100644
--- a/include/openthread/link.h
+++ b/include/openthread/link.h
@@ -279,11 +279,15 @@ OTAPI bool OTCALL otLinkIsInTransmitState(otInstance *aInstance);
 /**
  * This function enqueues an IEEE 802.15.4 out of band Frame for transmission.
  *
+ * An Out of Band frame is one that was generated outside of OpenThread.
+ *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aOobFrame  A pointer to the frame to transmit.
  *
- * @retval OT_ERROR_NONE           Successfully enqueued an IEEE 802.15.4 Data Request message.
- * @retval OT_ERROR_ALREADY        An IEEE 802.15.4 out of band frame is already enqueued.
+ * @retval OT_ERROR_NONE           Successfully scheduled the frame transmission.
+ * @retval OT_ERROR_ALREADY        MAC layer is busy sending a previously requested frame.
+ * @retval OT_ERROR_INVALID_STATE  The MAC layer is not enabled.
+ * @retval OT_ERROR_INVALID_ARGS   The argument @p aOobFrame is NULL.
  *
  */
 OTAPI otError OTCALL otLinkOutOfBandTransmitRequest(otInstance *aInstance, otRadioFrame *aOobFrame);
diff --git a/src/core/mac/mac.cpp b/src/core/mac/mac.cpp
index ee36f2b8e..499375e46 100644
--- a/src/core/mac/mac.cpp
+++ b/src/core/mac/mac.cpp
@@ -501,8 +501,10 @@ otError Mac::SendOutOfBandFrameRequest(otRadioFrame *aOobFrame)
 {
     otError error = OT_ERROR_NONE;
 
+    VerifyOrExit(aOobFrame != NULL, error = OT_ERROR_INVALID_ARGS);
     VerifyOrExit(mEnabled, error = OT_ERROR_INVALID_STATE);
-    VerifyOrExit(mOobFrame == NULL, error = OT_ERROR_ALREADY);
+    VerifyOrExit(!mPendingTransmitOobFrame && (mOperation != kOperationTransmitOutOfBandFrame),
+                 error = OT_ERROR_ALREADY);
 
     mOobFrame = static_cast<Frame *>(aOobFrame);
 
@@ -618,7 +620,6 @@ void Mac::PerformNextOperation(void)
         mPendingEnergyScan       = false;
         mPendingTransmitBeacon   = false;
         mPendingTransmitData     = false;
-        mOobFrame                = NULL;
         mTimer.Stop();
 #if OPENTHREAD_CONFIG_STAY_AWAKE_BETWEEN_FRAGMENTS
         mDelayingSleep    = false;
@@ -1196,7 +1197,6 @@ void Mac::HandleTransmitDone(Frame &aFrame, Frame *aAckFrame, otError aError)
         break;
 
     case kOperationTransmitOutOfBandFrame:
-        mOobFrame = NULL;
         FinishOperation();
         PerformNextOperation();
         break;
diff --git a/src/core/mac/mac.hpp b/src/core/mac/mac.hpp
index 1e4eea4d6..f7f41c7d4 100644
--- a/src/core/mac/mac.hpp
+++ b/src/core/mac/mac.hpp
@@ -235,6 +235,7 @@ public:
      * @retval OT_ERROR_NONE           Successfully scheduled the frame transmission.
      * @retval OT_ERROR_ALREADY        MAC layer is busy sending a previously requested frame.
      * @retval OT_ERROR_INVALID_STATE  The MAC layer is not enabled.
+     * @retval OT_ERROR_INVALID_ARGS   The argument @p aOobFrame is NULL.
      *
      */
     otError SendOutOfBandFrameRequest(otRadioFrame *aOobFrame);