[mle] add API to detach gracefully (#7666)

This commit adds an API `otThreadDetachGracefully` to notify other
nodes in the network (if any) and then stop Thread protocol
operation. It sends an Address Release if it's a router, or sets its
child timeout to 0 if it's a child.

include/openthread/instance.h

@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (216)
+#define OPENTHREAD_API_VERSION (217)
 
 /**
  * @addtogroup api-instance

include/openthread/thread.h

@@ -194,11 +194,22 @@ typedef struct otThreadParentResponseInfo
     bool         mIsAttached;   ///< Is the node receiving parent response attached
 } otThreadParentResponseInfo;
 
+/**
+ * This callback informs the application that the detaching process has finished.
+ *
+ * @param[in] aContext A pointer to application-specific context.
+ *
+ */
+typedef void (*otDetachGracefullyCallback)(void *aContext);
+
 /**
  * This function starts Thread protocol operation.
  *
  * The interface must be up when calling this function.
  *
+ * Calling this function with @p aEnabled set to FALSE stops any ongoing processes of detaching started by
+ * otThreadDetachGracefully(). Its callback will be called.
+ *
  * @param[in] aInstance A pointer to an OpenThread instance.
  * @param[in] aEnabled  TRUE if Thread is enabled, FALSE otherwise.
  *
@@ -1009,6 +1020,21 @@ otError otThreadSendProactiveBackboneNotification(otInstance *              aIns
                                                   otIp6InterfaceIdentifier *aMlIid,
                                                   uint32_t                  aTimeSinceLastTransaction);
 
+/**
+ * This function notifies other nodes in the network (if any) and then stops Thread protocol operation.
+ *
+ * It sends an Address Release if it's a router, or sets its child timeout to 0 if it's a child.
+ *
+ * @param[in] aInstance A pointer to an OpenThread instance.
+ * @param[in] aCallback A pointer to a function that is called upon finishing detaching.
+ * @param[in] aContext  A pointer to callback application-specific context.
+ *
+ * @retval OT_ERROR_NONE Successfully started detaching.
+ * @retval OT_ERROR_BUSY Detaching is already in progress.
+ *
+ */
+otError otThreadDetachGracefully(otInstance *aInstance, otDetachGracefullyCallback aCallback, void *aContext);
+
 /**
  * @}
  *