1 /* 2 * Copyright (c) 2016-2020, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for Thread neighbor table. 32 */ 33 34 #ifndef NEIGHBOR_TABLE_HPP_ 35 #define NEIGHBOR_TABLE_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include "common/locator.hpp" 40 #include "common/non_copyable.hpp" 41 #include "thread/neighbor.hpp" 42 43 namespace ot { 44 45 /** 46 * Represents the Thread neighbor table. 47 */ 48 class NeighborTable : public InstanceLocator, private NonCopyable 49 { 50 public: 51 /** 52 * Pointer is called to notify that a child or router neighbor is being added to or removed from 53 * neighbor table. 54 * 55 * Note that this callback in invoked while the neighbor/child table is being updated and always before the related 56 * `Notifier` event. 57 */ 58 typedef otNeighborTableCallback Callback; 59 60 /** 61 * Represents a neighbor table entry info (child or router) and is used as a parameter in the neighbor 62 * table callback. 63 */ 64 typedef otNeighborTableEntryInfo EntryInfo; 65 66 /** 67 * Defines the constants used in `NeighborTable::Callback` to indicate whether a child or router 68 * neighbor is being added or removed. 69 */ 70 enum Event : uint8_t 71 { 72 kChildAdded = OT_NEIGHBOR_TABLE_EVENT_CHILD_ADDED, ///< A child is being added. 73 kChildRemoved = OT_NEIGHBOR_TABLE_EVENT_CHILD_REMOVED, ///< A child is being removed. 74 kChildModeChanged = OT_NEIGHBOR_TABLE_EVENT_CHILD_MODE_CHANGED, ///< An existing child's mode changed. 75 kRouterAdded = OT_NEIGHBOR_TABLE_EVENT_ROUTER_ADDED, ///< A router is being added. 76 kRouterRemoved = OT_NEIGHBOR_TABLE_EVENT_ROUTER_REMOVED, ///< A router is being removed. 77 }; 78 79 /** 80 * Initializes the `NeighborTable` instance. 81 * 82 * @param[in] aInstance A reference to the OpenThread instance. 83 */ 84 explicit NeighborTable(Instance &aInstance); 85 86 /** 87 * Searches among parent and parent candidate to find a `Neighbor` corresponding to a given short 88 * address. 89 * 90 * @param[in] aShortAddress A short address. 91 * @param[in] aFilter A neighbor state filter 92 * 93 * @returns A pointer to the `Neighbor` corresponding to @p aShortAddress, `nullptr` otherwise. 94 */ 95 Neighbor *FindParent(Mac::ShortAddress aShortAddress, 96 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 97 98 /** 99 * Searches in parent and parent candidate to find a `Neighbor` corresponding to a given MAC Extended 100 * Address. 101 * 102 * @param[in] aExtAddress A MAC Extended Address. 103 * @param[in] aFilter A neighbor state filter 104 * 105 * @returns A pointer to the `Neighbor` corresponding to @p aExtAddress, `nullptr` otherwise. 106 */ 107 Neighbor *FindParent(const Mac::ExtAddress &aExtAddress, 108 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 109 110 /** 111 * Searches among parent and parent candidate to find a `Neighbor` object corresponding to a given MAC 112 * address. 113 * 114 * @param[in] aMacAddress A MAC address. 115 * @param[in] aFilter A neighbor state filter 116 * 117 * @returns A pointer to the `Neighbor` corresponding to @p aMacAddress, `nullptr` otherwise. 118 */ 119 Neighbor *FindParent(const Mac::Address &aMacAddress, 120 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 121 122 /** 123 * Searches in the neighbor table to find a `Neighbor` corresponding to a given short address. 124 * 125 * @param[in] aShortAddress A short address. 126 * @param[in] aFilter A neighbor state filter. 127 * 128 * @returns A pointer to the `Neighbor` corresponding to @p aShortAddress, `nullptr` otherwise. 129 */ 130 Neighbor *FindNeighbor(Mac::ShortAddress aShortAddress, 131 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 132 133 /** 134 * Searches in the neighbor table to find a `Neighbor` corresponding to a given MAC Extended Address. 135 * 136 * @param[in] aExtAddress A MAC Extended Address. 137 * @param[in] aFilter A neighbor state filter. 138 * 139 * @returns A pointer to the `Neighbor` corresponding to @p aExtAddress, `nullptr` otherwise. 140 */ 141 Neighbor *FindNeighbor(const Mac::ExtAddress &aExtAddress, 142 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 143 144 /** 145 * Searches in the neighbor table to find a `Neighbor` object corresponding to a given MAC address. 146 * 147 * @param[in] aMacAddress A MAC address. 148 * @param[in] aFilter A neighbor state filter. 149 * 150 * @returns A pointer to the `Neighbor` corresponding to @p aMacAddress, `nullptr` otherwise. 151 */ 152 Neighbor *FindNeighbor(const Mac::Address &aMacAddress, 153 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 154 155 #if OPENTHREAD_FTD 156 157 /** 158 * Searches in the neighbor table to find a `Neighbor` object corresponding to a given IPv6 address. 159 * 160 * @param[in] aIp6Address An IPv6 address. 161 * @pram[in] aFilter A neighbor state filter. 162 * 163 * @returns A pointer to the `Neighbor` corresponding to @p aIp6Address, `nullptr` otherwise. 164 */ 165 Neighbor *FindNeighbor(const Ip6::Address &aIp6Address, 166 Neighbor::StateFilter aFilter = Neighbor::kInStateValidOrRestoring); 167 168 /** 169 * Searches in the neighbor table to find a `Neighbor` for which a one-way link is maintained (as in the 170 * case of an FTD child with neighbor routers). 171 * 172 * @param[in] aExtAddress An Extended address. 173 * 174 * @returns A pointer to the Neighbor corresponding to @p aExtAddress, `nullptr` otherwise. 175 */ 176 Neighbor *FindRxOnlyNeighborRouter(const Mac::ExtAddress &aExtAddress); 177 178 /** 179 * Searches in the neighbor table to find a `Neighbor` for which a one-way link is maintained (as in the 180 * case of an FTD child with neighbor routers). 181 * 182 * @param[in] aMacAddress A MAC address. 183 * 184 * @returns A pointer to the Neighbor corresponding to @p aMacAddress, `nullptr` otherwise. 185 */ 186 Neighbor *FindRxOnlyNeighborRouter(const Mac::Address &aMacAddress); 187 188 #endif // OPENTHREAD_FTD 189 190 /** 191 * Gets the next neighbor information. It is used to iterate through the entries of 192 * the neighbor table. 193 * 194 * @param[in,out] aIterator A reference to the iterator context. To get the first neighbor entry 195 it should be set to OT_NEIGHBOR_INFO_ITERATOR_INIT. 196 * @param[out] aNeighInfo The neighbor information. 197 * 198 * @retval kErrorNone Successfully found the next neighbor entry in table. 199 * @retval kErrorNotFound No subsequent neighbor entry exists in the table. 200 */ 201 Error GetNextNeighborInfo(otNeighborInfoIterator &aIterator, Neighbor::Info &aNeighInfo); 202 203 /** 204 * Registers the "neighbor table changed" callback function. 205 * 206 * The provided callback (if non-`nullptr`) will be invoked when a child/router entry is being added/remove to/from 207 * the neighbor table. Subsequent calls to this method will overwrite the previous callback. 208 * 209 * @param[in] aCallback A pointer to callback handler function. 210 */ RegisterCallback(Callback aCallback)211 void RegisterCallback(Callback aCallback) { mCallback = aCallback; } 212 213 /** 214 * Signals a "neighbor table changed" event. 215 * 216 * Invokes the `NeighborTable::Callback` and also signals the change through a related `Notifier` event. 217 * 218 * @param[in] aEvent The event to emit (child/router added/removed, or child mode changed). 219 * @param[in] aNeighbor The neighbor that is being added/removed. 220 */ 221 void Signal(Event aEvent, const Neighbor &aNeighbor); 222 223 private: 224 Neighbor *FindParent(const Neighbor::AddressMatcher &aMatcher); 225 Neighbor *FindNeighbor(const Neighbor::AddressMatcher &aMatcher); 226 #if OPENTHREAD_FTD 227 Neighbor *FindChildOrRouter(const Neighbor::AddressMatcher &aMatcher); 228 #endif 229 230 Callback mCallback; 231 }; 232 233 } // namespace ot 234 235 #endif // NEIGHBOR_TABLE_HPP_ 236