From f27b64dc59c1c7e60747bda495681503ccffa685 Mon Sep 17 00:00:00 2001
From: Abtin Keshavarzian <abtink@google.com>
Date: Mon, 19 Mar 2018 15:47:28 -0700
Subject: [PATCH] [channel-monitor] add public OT API to enable/disable channel
 monitoring (#2623)

---
 include/openthread/channel_monitor.h | 28 ++++++++++++++++++++++++++++
 src/core/api/channel_monitor_api.cpp | 14 ++++++++++++++
 src/core/utils/channel_monitor.cpp   | 16 ++++++++++++++--
 src/core/utils/channel_monitor.hpp   | 22 ++++++++++++++++++----
 4 files changed, 74 insertions(+), 6 deletions(-)

diff --git a/include/openthread/channel_monitor.h b/include/openthread/channel_monitor.h
index 84263cc33..042e8b45a 100644
--- a/include/openthread/channel_monitor.h
+++ b/include/openthread/channel_monitor.h
@@ -62,6 +62,34 @@ extern "C" {
  *
  */
 
+/**
+ * This function enables/disables the Channel Monitoring operation.
+ *
+ * Once operation starts, any previously collected data is cleared. However, after operation is disabled, the previous
+ * collected data is still valid and can be read.
+ *
+ * @note OpenThread core internally enables/disables the Channel Monitoring operation when the IPv6 interface is
+ * brought up/down (i.e., call to `otIp6SetEnabled()`).
+ *
+ * @param[in]  aInstance       A pointer to an OpenThread instance.
+ * @param[in]  aEnabled        TRUE to enable/start Channel Monitoring operation, FALSE to disable/stop it.
+ *
+ * @retval OT_ERROR_NONE      Channel Monitoring state changed successfully
+ * @retval OT_ERROR_ALREADY   Channel Monitoring is already in the same state.
+ *
+ */
+otError otChannelMonitorSetEnabled(otInstance *aInstance, bool aEnabled);
+
+/**
+ * This function indicates whether the Channel Monitoring operation is enabled and running.
+ *
+ * @param[in]  aInstance       A pointer to an OpenThread instance.
+ *
+ * @returns TRUE if the Channel Monitoring operation is enabled, FALSE otherwise.
+ *
+ */
+bool otChannelMonitorIsEnabled(otInstance *aInstance);
+
 /**
  * Get channel monitoring sample interval in milliseconds.
  *
diff --git a/src/core/api/channel_monitor_api.cpp b/src/core/api/channel_monitor_api.cpp
index 73121c7c0..48bbb2546 100644
--- a/src/core/api/channel_monitor_api.cpp
+++ b/src/core/api/channel_monitor_api.cpp
@@ -40,6 +40,20 @@ using namespace ot;
 
 #if OPENTHREAD_ENABLE_CHANNEL_MONITOR
 
+otError otChannelMonitorSetEnabled(otInstance *aInstance, bool aEnabled)
+{
+    Utils::ChannelMonitor monitor = static_cast<Instance *>(aInstance)->GetChannelMonitor();
+
+    return aEnabled ? monitor.Start() : monitor.Stop();
+}
+
+bool otChannelMonitorIsEnabled(otInstance *aInstance)
+{
+    Instance &instance = *static_cast<Instance *>(aInstance);
+
+    return instance.GetChannelMonitor().IsRunning();
+}
+
 uint32_t otChannelMonitorGetSampleInterval(otInstance *aInstance)
 {
     OT_UNUSED_VARIABLE(aInstance);
diff --git a/src/core/utils/channel_monitor.cpp b/src/core/utils/channel_monitor.cpp
index e303d957b..42efe564b 100644
--- a/src/core/utils/channel_monitor.cpp
+++ b/src/core/utils/channel_monitor.cpp
@@ -59,17 +59,29 @@ ChannelMonitor::ChannelMonitor(Instance &aInstance)
     memset(mChannelQuality, 0, sizeof(mChannelQuality));
 }
 
-void ChannelMonitor::Start(void)
+otError ChannelMonitor::Start(void)
 {
+    otError error = OT_ERROR_NONE;
+
+    VerifyOrExit(!IsRunning(), error = OT_ERROR_ALREADY);
     Clear();
     mTimer.Start(kTimerInterval);
     otLogDebgUtil(GetInstance(), "ChannelMonitor: Starting");
+
+exit:
+    return error;
 }
 
-void ChannelMonitor::Stop(void)
+otError ChannelMonitor::Stop(void)
 {
+    otError error = OT_ERROR_NONE;
+
+    VerifyOrExit(IsRunning(), error = OT_ERROR_ALREADY);
     mTimer.Stop();
     otLogDebgUtil(GetInstance(), "ChannelMonitor: Stopping");
+
+exit:
+    return error;
 }
 
 void ChannelMonitor::Clear(void)
diff --git a/src/core/utils/channel_monitor.hpp b/src/core/utils/channel_monitor.hpp
index 1b9096e70..d54f7f0f3 100644
--- a/src/core/utils/channel_monitor.hpp
+++ b/src/core/utils/channel_monitor.hpp
@@ -106,18 +106,32 @@ public:
     /**
      * This method starts the Channel Monitoring operation.
      *
-     * All previous data is cleared when the Channel Monitoring operation starts.
+     * Once started, any previously collected data is cleared.
+     *
+     * @retval OT_ERROR_NONE      Channel Monitoring started successfully.
+     * @retval OT_ERROR_ALREADY   Channel Monitoring has already been started.
      *
      */
-    void Start(void);
+    otError Start(void);
 
     /**
      * This method stops the Channel Monitoring operation.
      *
-     * The previous data is still valid and can be read while the operation is stopped.
+     * @note After `Stop()`, the previous data is still valid and can be read.
+     *
+     * @retval OT_ERROR_NONE      Channel Monitoring stopped successfully.
+     * @retval OT_ERROR_ALREADY   Channel Monitoring has already been stopped.
      *
      */
-    void Stop(void);
+    otError Stop(void);
+
+    /**
+     * This method indicates whether the Channel Monitoring operation is started and running.
+     *
+     * @returns TRUE if the Channel Monitoring operation is running, FALSE otherwise.
+     *
+     */
+    bool IsRunning(void) const { return mTimer.IsRunning(); }
 
     /**
      * This method clears all currently stored data.