[neighbor-table] new event to signal child mode change (#6939)

This commits adds a new `otNeighborTableEvent` which indicates that a
child's Device Mode is changed (in addition to existing events which
indicate that a child or a router neighbor is being added or
removed).

include/openthread/thread_ftd.h

@@ -643,16 +643,16 @@ uint8_t otThreadGetMaxChildIpAddresses(otInstance *aInstance);
 otError otThreadSetMaxChildIpAddresses(otInstance *aInstance, uint8_t aMaxIpAddresses);
 
 /**
- * This enumeration defines the constants used in `otNeighborTableCallback` to indicate whether a child or router
- * neighbor is being added or removed.
+ * This enumeration defines the constants used in `otNeighborTableCallback` to indicate changes in neighbor table.
  *
  */
 typedef enum
 {
-    OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED,    ///< A child is being added.
-    OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED,  ///< A child is being removed.
-    OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED,   ///< A router is being added.
-    OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed.
+    OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED,        ///< A child is being added.
+    OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED,      ///< A child is being removed.
+    OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode is changed.
+    OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED,       ///< A router is being added.
+    OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED,     ///< A router is being removed.
 } otNeighborTableEvent;
 
 /**
@@ -671,8 +671,7 @@ typedef struct
 } otNeighborTableEntryInfo;
 
 /**
- * This function pointer is called to notify that a child or router neighbor is being added to or removed from neighbor
- * table.
+ * This function pointer is called to notify that there is a change in the neighbor table.
  *
  * @param[in]  aEvent      A event flag.
  * @param[in]  aEntryInfo  A pointer to table entry info.
@@ -683,9 +682,11 @@ typedef void (*otNeighborTableCallback)(otNeighborTableEvent aEvent, const otNei
 /**
  * This function registers a neighbor table callback function.
  *
- * The provided callback (if non-NULL) will be invoked when a child or router neighbor entry is being added/removed
- * to/from the neighbor table. Subsequent calls to this method will overwrite the previous callback.  Note that this
- * callback in invoked while the neighbor/child table is being updated and always before the `otStateChangedCallback`.
+ * The provided callback (if non-NULL) will be invoked when there is a change in the neighbor table (e.g., a child or a
+ * router neighbor entry is being added/removed or an existing child's mode is changed).
+ *
+ * Subsequent calls to this method will overwrite the previous callback.  Note that this callback in invoked while the
+ * neighbor/child table is being updated and always before the `otStateChangedCallback`.
  *
  * @param[in] aInstance  A pointer to an OpenThread instance.
  * @param[in] aCallback  A pointer to callback handler function.

src/core/thread/mle_router.cpp

@@ -979,7 +979,7 @@ Error MleRouter::HandleLinkAccept(const Message &         aMessage,
     router->SetState(Neighbor::kStateValid);
     router->SetKeySequence(aKeySequence);
 
-    mNeighborTable.Signal(OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, *router);
+    mNeighborTable.Signal(NeighborTable::kRouterAdded, *router);
 
     if (aRequest)
     {
@@ -3378,7 +3378,7 @@ void MleRouter::RemoveNeighbor(Neighbor &aNeighbor)
 
         if (aNeighbor.IsStateValidOrRestoring())
         {
-            mNeighborTable.Signal(OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, aNeighbor);
+            mNeighborTable.Signal(NeighborTable::kChildRemoved, aNeighbor);
         }
 
         Get<IndirectSender>().ClearAllMessagesForSleepyChild(static_cast<Child &>(aNeighbor));
@@ -3395,7 +3395,7 @@ void MleRouter::RemoveNeighbor(Neighbor &aNeighbor)
     {
         OT_ASSERT(mRouterTable.Contains(aNeighbor));
 
-        mNeighborTable.Signal(OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, aNeighbor);
+        mNeighborTable.Signal(NeighborTable::kRouterRemoved, aNeighbor);
         mRouterTable.RemoveRouterLink(static_cast<Router &>(aNeighbor));
     }
 
@@ -4315,7 +4315,7 @@ void MleRouter::SetChildStateToValid(Child &aChild)
     Get<MlrManager>().UpdateProxiedSubscriptions(aChild, nullptr, 0);
 #endif
 
-    mNeighborTable.Signal(OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, aChild);
+    mNeighborTable.Signal(NeighborTable::kChildAdded, aChild);
 
 exit:
     return;

src/core/thread/neighbor_table.cpp

@@ -265,20 +265,21 @@ void NeighborTable::Signal(Event aEvent, const Neighbor &aNeighbor)
 
         switch (aEvent)
         {
-        case OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED:
-        case OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED:
+        case kChildAdded:
+        case kChildRemoved:
+        case kChildModeChanged:
 #if OPENTHREAD_FTD
             static_cast<Child::Info &>(info.mInfo.mChild).SetFrom(static_cast<const Child &>(aNeighbor));
 #endif
             break;
 
-        case OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED:
-        case OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED:
+        case kRouterAdded:
+        case kRouterRemoved:
             static_cast<Neighbor::Info &>(info.mInfo.mRouter).SetFrom(aNeighbor);
             break;
         }
 
-        mCallback(aEvent, &info);
+        mCallback(static_cast<otNeighborTableEvent>(aEvent), &info);
     }
 
 #if OPENTHREAD_CONFIG_OTNS_ENABLE
@@ -287,11 +288,11 @@ void NeighborTable::Signal(Event aEvent, const Neighbor &aNeighbor)
 
     switch (aEvent)
     {
-    case OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED:
+    case kChildAdded:
         Get<Notifier>().Signal(kEventThreadChildAdded);
         break;
 
-    case OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED:
+    case kChildRemoved:
         Get<Notifier>().Signal(kEventThreadChildRemoved);
 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_DUA_ENABLE
         Get<DuaManager>().UpdateChildDomainUnicastAddress(static_cast<const Child &>(aNeighbor),

src/core/thread/neighbor_table.hpp

@@ -71,7 +71,14 @@ public:
      * neighbor is being added or removed.
      *
      */
-    typedef otNeighborTableEvent Event;
+    enum Event : uint8_t
+    {
+        kChildAdded       = OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED,        ///< A child is being added.
+        kChildRemoved     = OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED,      ///< A child is being removed.
+        kChildModeChanged = OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode changed.
+        kRouterAdded      = OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED,       ///< A router is being added.
+        kRouterRemoved    = OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED,     ///< A router is being removed.
+    };
 
     /**
      * This constructor initializes the `NeighborTable` instance.
@@ -213,7 +220,7 @@ public:
      *
      * This method invokes the `NeighborTable::Callback` and also signals the change through a related `Notifier` event.
      *
-     * @param[in] aEvent     The event to emit (child/router added/removed).
+     * @param[in] aEvent     The event to emit (child/router added/removed, or child mode changed).
      * @param[in] aNeighbor  The neighbor that is being added/removed.
      *
      */

src/core/thread/router_table.cpp

@@ -100,7 +100,7 @@ void RouterTable::ClearNeighbors(void)
     {
         if (router.IsStateValid())
         {
-            Get<NeighborTable>().Signal(OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, router);
+            Get<NeighborTable>().Signal(NeighborTable::kRouterRemoved, router);
         }
 
         router.SetState(Neighbor::kStateInvalid);

src/core/thread/topology.cpp

@@ -294,6 +294,19 @@ void Child::ClearIp6Addresses(void)
 #endif
 }
 
+void Child::SetDeviceMode(Mle::DeviceMode aMode)
+{
+    VerifyOrExit(aMode != GetDeviceMode());
+
+    Neighbor::SetDeviceMode(aMode);
+
+    VerifyOrExit(IsStateValid());
+    Get<NeighborTable>().Signal(NeighborTable::kChildModeChanged, *this);
+
+exit:
+    return;
+}
+
 Error Child::GetMeshLocalIp6Address(Ip6::Address &aAddress) const
 {
     Error error = kErrorNone;

src/core/thread/topology.hpp

@@ -1010,6 +1010,14 @@ public:
      */
     void ClearIp6Addresses(void);
 
+    /**
+     * This method sets the device mode flags.
+     *
+     * @param[in]  aMode  The device mode flags.
+     *
+     */
+    void SetDeviceMode(Mle::DeviceMode aMode);
+
     /**
      * This method gets the mesh-local IPv6 address.
      *

src/core/utils/otns.cpp

@@ -112,18 +112,20 @@ void Otns::EmitNeighborChange(NeighborTable::Event aEvent, const Neighbor &aNeig
 {
     switch (aEvent)
     {
-    case OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED:
+    case NeighborTable::kRouterAdded:
         EmitStatus("router_added=%s", aNeighbor.GetExtAddress().ToString().AsCString());
         break;
-    case OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED:
+    case NeighborTable::kRouterRemoved:
         EmitStatus("router_removed=%s", aNeighbor.GetExtAddress().ToString().AsCString());
         break;
-    case OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED:
+    case NeighborTable::kChildAdded:
         EmitStatus("child_added=%s", aNeighbor.GetExtAddress().ToString().AsCString());
         break;
-    case OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED:
+    case NeighborTable::kChildRemoved:
         EmitStatus("child_removed=%s", aNeighbor.GetExtAddress().ToString().AsCString());
         break;
+    case NeighborTable::kChildModeChanged:
+        break;
     }
 }