[data-poll-manager] check user-specified poll period (#3401)

examples/apps/windows/otAdapter.h

@@ -164,7 +164,7 @@ public:
     property uint32_t PollPeriod
     {
         uint32_t get() { return otLinkGetPollPeriod(DeviceInstance); }
-        void set(uint32_t value) { otLinkSetPollPeriod(DeviceInstance, value); }
+        void set(uint32_t value) { ThrowOnFailure(otLinkSetPollPeriod(DeviceInstance, value)); }
     }
 
     property uint8_t Channel

examples/drivers/windows/otApi/otApi.cpp

@@ -2424,15 +2424,19 @@ otLinkGetPollPeriod(
     return Result;
 }
 
-OTAPI 
-void 
+OTAPI
+otError
 OTCALL
 otLinkSetPollPeriod(
-    _In_ otInstance *aInstance, 
+    _In_ otInstance *aInstance,
     uint32_t aPollPeriod
     )
 {
-    if (aInstance) (void)SetIOCTL(aInstance, IOCTL_OTLWF_OT_POLL_PERIOD, aPollPeriod);
+    otError result = OT_ERROR_INVALID_ARGS;
+
+    if (aInstance) result = DwordToThreadError(SetIOCTL(aInstance, IOCTL_OTLWF_OT_POLL_PERIOD, aPollPeriod));
+
+    return result;
 }
 
 OTAPI

examples/drivers/windows/otLwf/iocontrol.c

@@ -4971,8 +4971,7 @@ otLwfIoCtl_otPollPeriod(
 
     if (InBufferLength >= sizeof(uint32_t))
     {
-        otLinkSetPollPeriod(pFilter->otCtx, *(uint32_t*)InBuffer);
-        status = STATUS_SUCCESS;
+        status = ThreadErrorToNtstatus(otLinkSetPollPeriod(pFilter->otCtx, *(uint32_t*)InBuffer));
         *OutBufferLength = 0;
     }
     else if (*OutBufferLength >= sizeof(uint32_t))

include/openthread/link.h

@@ -418,18 +418,24 @@ OTAPI otError OTCALL otLinkSetPanId(otInstance *aInstance, otPanId aPanId);
 OTAPI uint32_t OTCALL otLinkGetPollPeriod(otInstance *aInstance);
 
 /**
- * Set the data poll period for sleepy end device.
+ * Set/clear user-specified/external data poll period for sleepy end device.
  *
  * @note This function updates only poll period of sleepy end device. To update child timeout the function
  *       `otSetChildTimeout()` shall be called.
  *
+ * @note Minimal non-zero value should be `OPENTHREAD_CONFIG_MINIMUM_POLL_PERIOD` (10ms).
+ *       Or zero to clear user-specified poll period.
+ *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
  * @param[in]  aPollPeriod  data poll period in milliseconds.
  *
+ * @retval OT_ERROR_NONE           Successfully set/cleared user-specified poll period.
+ * @retval OT_ERROR_INVALID_ARGS   If aPollPeriod is invalid.
+ *
  * @sa otLinkGetPollPeriod
  *
  */
-OTAPI void OTCALL otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod);
+OTAPI otError OTCALL otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod);
 
 /**
  * Get the IEEE 802.15.4 Short Address.

src/cli/cli.cpp

@@ -2001,8 +2001,7 @@ void Interpreter::ProcessPollPeriod(int argc, char *argv[])
     else
     {
         SuccessOrExit(error = ParseLong(argv[0], value));
-        VerifyOrExit(value >= OPENTHREAD_CONFIG_MINIMUM_POLL_PERIOD, error = OT_ERROR_PARSE);
-        otLinkSetPollPeriod(mInstance, static_cast<uint32_t>(value));
+        error = otLinkSetPollPeriod(mInstance, static_cast<uint32_t>(value));
     }
 
 exit:

src/core/api/link_api.cpp

@@ -145,11 +145,11 @@ uint32_t otLinkGetPollPeriod(otInstance *aInstance)
     return instance.GetThreadNetif().GetMeshForwarder().GetDataPollManager().GetKeepAlivePollPeriod();
 }
 
-void otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod)
+otError otLinkSetPollPeriod(otInstance *aInstance, uint32_t aPollPeriod)
 {
     Instance &instance = *static_cast<Instance *>(aInstance);
 
-    instance.GetThreadNetif().GetMeshForwarder().GetDataPollManager().SetExternalPollPeriod(aPollPeriod);
+    return instance.GetThreadNetif().GetMeshForwarder().GetDataPollManager().SetExternalPollPeriod(aPollPeriod);
 }
 
 otError otLinkSendDataRequest(otInstance *aInstance)

src/core/thread/data_poll_manager.cpp

@@ -161,8 +161,15 @@ exit:
     return error;
 }
 
-void DataPollManager::SetExternalPollPeriod(uint32_t aPeriod)
+otError DataPollManager::SetExternalPollPeriod(uint32_t aPeriod)
 {
+    otError error = OT_ERROR_NONE;
+
+    if (aPeriod != 0 && aPeriod < OPENTHREAD_CONFIG_MINIMUM_POLL_PERIOD)
+    {
+        ExitNow(error = OT_ERROR_INVALID_ARGS);
+    }
+
     if (mExternalPollPeriod != aPeriod)
     {
         mExternalPollPeriod = aPeriod;
@@ -172,6 +179,9 @@ void DataPollManager::SetExternalPollPeriod(uint32_t aPeriod)
             ScheduleNextPoll(kRecalculatePollPeriod);
         }
     }
+
+exit:
+    return error;
 }
 
 uint32_t DataPollManager::GetKeepAlivePollPeriod(void) const

src/core/thread/data_poll_manager.hpp

@@ -102,18 +102,22 @@ public:
     otError SendDataPoll(void);
 
     /**
-     * This method sets a user-specified/external data poll period.
+     * This method sets/clears a user-specified/external data poll period.
      *
      * If the user provides a non-zero poll period, the user value specifies the maximum period between data
      * request transmissions. Note that OpenThread may send data request transmissions more frequently when expecting
      * a control-message from a parent or in case of data poll transmission failures or timeouts.
      *
-     * Default value for the external poll period is zero (i.e., no user-specified poll period).
+     * Minimal non-zero value should be `OPENTHREAD_CONFIG_MINIMUM_POLL_PERIOD` (10ms). Or zero to clear user-specified
+     * poll period.
      *
-     * @param[in]  aPeriod  The data poll period in milliseconds, or zero to mean no user-specified poll period.
+     * @param[in]  aPeriod  The data poll period in milliseconds.
+     *
+     * @retval OT_ERROR_NONE           Successfully set/cleared user-specified poll period.
+     * @retval OT_ERROR_INVALID_ARGS   If aPeriod is invalid.
      *
      */
-    void SetExternalPollPeriod(uint32_t aPeriod);
+    otError SetExternalPollPeriod(uint32_t aPeriod);
 
     /**
      * This method gets the current user-specified/external data poll period.

src/ncp/ncp_base_mtd.cpp

@@ -175,7 +175,7 @@ template <> otError NcpBase::HandlePropertySet<SPINEL_PROP_MAC_DATA_POLL_PERIOD>
 
     SuccessOrExit(error = mDecoder.ReadUint32(pollPeriod));
 
-    otLinkSetPollPeriod(mInstance, pollPeriod);
+    error = otLinkSetPollPeriod(mInstance, pollPeriod);
 
 exit:
     return error;