[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

@@ -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);

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;

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);