[dbus] return delay timer from `AttachAllNodesTo` (#1430)

This commit:
1. Makes the DBus API `AttachAllNodesTo` return the delay between the
method returns and the dataset takes effect.
2. Ensures that when `AttachAllNodesTo` returns, the node is attached.

3 files changed, 34 insertions, 9 deletions

diff --git a/src/dbus/server/dbus_request.hpp b/src/dbus/server/dbus_request.hpp
index c1455e2f..9c89bfd0 100644
--- a/src/dbus/server/dbus_request.hpp
+++ b/src/dbus/server/dbus_request.hpp
@@ -35,6 +35,7 @@
 #define OTBR_LOG_TAG "DBUS"
 #endif
 
+#include "common/code_utils.hpp"
 #include "common/logging.hpp"
 
 #include "dbus/common/dbus_message_dump.hpp"
@@ -136,9 +137,11 @@ public:
      * This method replies an otError to the d-bus method call.
      *
      * @param[in] aError  The error to be sent.
+     * @param[in] aResult The return value of the method call, if any.
      *
      */
-    void ReplyOtResult(otError aError)
+    template <typename ResultType = int>
+    void ReplyOtResult(otError aError, Optional<ResultType> aResult = Optional<ResultType>())
     {
         UniqueDBusMessage reply{nullptr};
 
@@ -161,12 +164,19 @@ public:
         {
             reply = UniqueDBusMessage(dbus_message_new_error(mMessage, ConvertToDBusErrorName(aError), nullptr));
         }
+        VerifyOrDie(reply != nullptr, "Failed to allocate message");
 
-        VerifyOrExit(reply != nullptr);
-        dbus_connection_send(mConnection, reply.get(), nullptr);
+        if (aResult.HasValue())
+        {
+            DBusMessageIter replyIter;
+            otbrError       error;
 
-    exit:
-        return;
+            dbus_message_iter_init_append(reply.get(), &replyIter);
+            error = DBusMessageEncode(&replyIter, *aResult);
+            VerifyOrDie(error == OTBR_ERROR_NONE, "Failed to encode result");
+        }
+
+        dbus_connection_send(mConnection, reply.get(), nullptr);
     }
 
     /**
diff --git a/src/dbus/server/dbus_thread_object.cpp b/src/dbus/server/dbus_thread_object.cpp
index 179de241..c9b29dd1 100644
--- a/src/dbus/server/dbus_thread_object.cpp
+++ b/src/dbus/server/dbus_thread_object.cpp
@@ -338,7 +338,11 @@ void DBusThreadObject::AttachHandler(DBusRequest &aRequest)
 
     if (IsDBusMessageEmpty(*aRequest.GetMessage()))
     {
-        threadHelper->Attach([aRequest](otError aError) mutable { aRequest.ReplyOtResult(aError); });
+        threadHelper->Attach([aRequest](otError aError, int64_t aAttachDelayMs) mutable {
+            OT_UNUSED_VARIABLE(aAttachDelayMs);
+
+            aRequest.ReplyOtResult(aError);
+        });
     }
     else if (DBusMessageToTuple(*aRequest.GetMessage(), args) != OTBR_ERROR_NONE)
     {
@@ -347,7 +351,11 @@ void DBusThreadObject::AttachHandler(DBusRequest &aRequest)
     else
     {
         threadHelper->Attach(name, panid, extPanId, networkKey, pskc, channelMask,
-                             [aRequest](otError aError) mutable { aRequest.ReplyOtResult(aError); });
+                             [aRequest](otError aError, int64_t aAttachDelayMs) mutable {
+                                 OT_UNUSED_VARIABLE(aAttachDelayMs);
+
+                                 aRequest.ReplyOtResult(aError);
+                             });
     }
 }
 
@@ -360,8 +368,9 @@ void DBusThreadObject::AttachAllNodesToHandler(DBusRequest &aRequest)
 
     VerifyOrExit(DBusMessageToTuple(*aRequest.GetMessage(), args) == OTBR_ERROR_NONE, error = OT_ERROR_INVALID_ARGS);
 
-    mNcp->GetThreadHelper()->AttachAllNodesTo(dataset,
-                                              [aRequest](otError error) mutable { aRequest.ReplyOtResult(error); });
+    mNcp->GetThreadHelper()->AttachAllNodesTo(dataset, [aRequest](otError error, int64_t aAttachDelayMs) mutable {
+        aRequest.ReplyOtResult<int64_t>(error, aAttachDelayMs);
+    });
 
 exit:
     if (error != OT_ERROR_NONE)
diff --git a/src/dbus/server/introspect.xml b/src/dbus/server/introspect.xml
index 5c399572..8a28f2de 100644
--- a/src/dbus/server/introspect.xml
+++ b/src/dbus/server/introspect.xml
@@ -60,9 +60,15 @@
     <!-- AttachAllNodesTo: Request to attach all nodes to the specified Thread network.
       @dataset: The Operational Dataset that contains parameter values of the Thread network
                 to attach to. It must be a full dataset.
+      @delay_ms: The delay between the method returns and the dataset takes effect, in
+                 milliseconds. If this value is 0, then the node is attached to the given network
+                 when this method returns. If this value is not 0, then the node is attached to
+                 its existing network when this method returns, and will attach to the given
+                 network after the delay.
     -->
     <method name="AttachAllNodesTo">
       <arg name="dataset" type="ay"/>
+      <arg name="delay_ms" type="x" direction="out"/>
     </method>
 
     <!-- Detach: Detach the current device from the Thread network. -->