[dhcp] add callback to notify DHCPv6 PD state change (#9926)

When the DHCPv6 PD state changed, we need to throw out a signal to
notify another process running on the OS, then the process will decide
if it need to withdraw or request RA.

include/openthread/border_routing.h

@@ -498,6 +498,31 @@ void otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled);
  */
 otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState(otInstance *aInstance);
 
+/**
+ * When the state of a DHCPv6 Prefix Delegation (PD) on the Thread interface changes, this callback notifies processes
+ * in the OS of this changed state.
+ *
+ * @param[in] aState    The state of DHCPv6 Prefix Delegation State.
+ * @param[in] aContext  A pointer to arbitrary context information.
+ *
+ */
+typedef void (*otBorderRoutingRequestDhcp6PdCallback)(otBorderRoutingDhcp6PdState aState, void *aContext);
+
+/**
+ * Sets the callback whenever the DHCPv6 PD state changes on the Thread interface.
+ *
+ * Subsequent calls to this function replace the previously set callback.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ * @param[in] aCallback  A pointer to a function that is called whenever the DHCPv6 PD state changes.
+ * @param[in] aContext   A pointer to arbitrary context information.
+ *
+ *
+ */
+void otBorderRoutingDhcp6PdSetRequestCallback(otInstance                           *aInstance,
+                                              otBorderRoutingRequestDhcp6PdCallback aCallback,
+                                              void                                 *aContext);
+
 /**
  * @}
  *

include/openthread/instance.h

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

src/core/api/border_routing_api.cpp

@@ -205,6 +205,14 @@ otBorderRoutingDhcp6PdState otBorderRoutingDhcp6PdGetState(otInstance *aInstance
     return static_cast<otBorderRoutingDhcp6PdState>(
         AsCoreType(aInstance).Get<BorderRouter::RoutingManager>().GetDhcp6PdState());
 }
+
+void otBorderRoutingDhcp6PdSetRequestCallback(otInstance                           *aInstance,
+                                              otBorderRoutingRequestDhcp6PdCallback aCallback,
+                                              void                                 *aContext)
+{
+    AsCoreType(aInstance).Get<BorderRouter::RoutingManager>().SetRequestDhcp6PdCallback(aCallback, aContext);
+}
+
 #endif
 
 #endif // OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE

src/core/border_router/routing_manager.cpp

@@ -3642,6 +3642,8 @@ void RoutingManager::PdPrefixManager::EvaluateStateChange(Dhcp6PdState aOldState
         break;
     }
 
+    mExternalCallback.InvokeIfSet(static_cast<otBorderRoutingDhcp6PdState>(newState));
+
 exit:
     return;
 }

src/core/border_router/routing_manager.hpp

@@ -47,11 +47,13 @@
 #error "OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE is required for OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE."
 #endif
 
+#include <openthread/border_routing.h>
 #include <openthread/nat64.h>
 #include <openthread/netdata.h>
 
 #include "border_router/infra_if.hpp"
 #include "common/array.hpp"
+#include "common/callback.hpp"
 #include "common/error.hpp"
 #include "common/heap_allocatable.hpp"
 #include "common/heap_array.hpp"
@@ -86,11 +88,12 @@ class RoutingManager : public InstanceLocator
     friend class ot::Instance;
 
 public:
-    typedef NetworkData::RoutePreference       RoutePreference;     ///< Route preference (high, medium, low).
+    typedef NetworkData::RoutePreference          RoutePreference;     ///< Route preference (high, medium, low).
-    typedef otBorderRoutingPrefixTableIterator PrefixTableIterator; ///< Prefix Table Iterator.
+    typedef otBorderRoutingPrefixTableIterator    PrefixTableIterator; ///< Prefix Table Iterator.
-    typedef otBorderRoutingPrefixTableEntry    PrefixTableEntry;    ///< Prefix Table Entry.
+    typedef otBorderRoutingPrefixTableEntry       PrefixTableEntry;    ///< Prefix Table Entry.
-    typedef otBorderRoutingRouterEntry         RouterEntry;         ///< Router Entry.
+    typedef otBorderRoutingRouterEntry            RouterEntry;         ///< Router Entry.
-    typedef otPdProcessedRaInfo                PdProcessedRaInfo;   ///< Data of PdProcessedRaInfo.
+    typedef otPdProcessedRaInfo                   PdProcessedRaInfo;   ///< Data of PdProcessedRaInfo.
+    typedef otBorderRoutingRequestDhcp6PdCallback PdCallback;          ///< DHCPv6 PD callback.
 
     /**
      * This constant specifies the maximum number of route prefixes that may be published by `RoutingManager`
@@ -569,6 +572,21 @@ public:
      *
      */
     Dhcp6PdState GetDhcp6PdState(void) const { return mPdPrefixManager.GetState(); }
+
+    /**
+     * Sets the callback whenever the state of a prefix request or release, via the DHCPv6 Prefix Delegation (PD),
+     * changes on the Thread interface.
+     *
+     * @param[in] aCallback  A pointer to a function that is called whenever the state of a prefix request or release
+     * changes.
+     * @param[in] aContext   A pointer to arbitrary context information.
+     *
+     */
+    void SetRequestDhcp6PdCallback(PdCallback aCallback, void *aContext)
+    {
+        mPdPrefixManager.SetRequestDhcp6PdCallback(aCallback, aContext);
+    }
+
 #endif // OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE
 
 private:
@@ -1295,6 +1313,10 @@ private:
         Error GetPrefixInfo(PrefixTableEntry &aInfo) const;
         Error GetProcessedRaInfo(PdProcessedRaInfo &aPdProcessedRaInfo) const;
         void  HandleTimer(void) { WithdrawPrefix(); }
+        void  SetRequestDhcp6PdCallback(PdCallback aCallback, void *aContext)
+        {
+            mExternalCallback.Set(aCallback, aContext);
+        }
 
         static const char *StateToString(Dhcp6PdState aState);
 
@@ -1313,15 +1335,18 @@ private:
         void  StartStop(bool aStart);
 
         using PlatformOmrPrefixTimer = TimerMilliIn<RoutingManager, &RoutingManager::HandlePdPrefixManagerTimer>;
+        using ExternalCallback       = Callback<PdCallback>;
 
         bool                         mEnabled;
         bool                         mIsRunning;
         uint32_t                     mNumPlatformPioProcessed;
         uint32_t                     mNumPlatformRaReceived;
         TimeMilli                    mLastPlatformRaTime;
+        ExternalCallback             mExternalCallback;
         PlatformOmrPrefixTimer       mTimer;
         DiscoveredPrefixTable::Entry mPrefix;
     };
+
 #endif // OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE
 
     void  EvaluateState(void);