1 /* 2 * Copyright (c) 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 Multicast Listeners Table. 32 */ 33 34 #ifndef MULTICAST_LISTENERS_TABLE_HPP 35 #define MULTICAST_LISTENERS_TABLE_HPP 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE 40 41 #include <openthread/backbone_router_ftd.h> 42 43 #include "common/non_copyable.hpp" 44 #include "common/notifier.hpp" 45 #include "common/time.hpp" 46 #include "net/ip6_address.hpp" 47 48 namespace ot { 49 50 namespace BackboneRouter { 51 52 /** 53 * This class implements the definitions for Multicast Listeners Table. 54 * 55 */ 56 class MulticastListenersTable : public InstanceLocator, private NonCopyable 57 { 58 class IteratorBuilder; 59 60 public: 61 /** 62 * This class represents a Multicast Listener entry. 63 * 64 */ 65 class Listener : public Clearable<Listener> 66 { 67 friend class MulticastListenersTable; 68 69 public: 70 /** 71 * This constructor initializes the `Listener` object. 72 * 73 */ Listener(void)74 Listener(void) { Clear(); } 75 76 /** 77 * This method returns the Multicast Listener address. 78 * 79 * @returns The Multicast Listener address. 80 * 81 */ GetAddress(void) const82 const Ip6::Address &GetAddress(void) const { return mAddress; } 83 84 /** 85 * This method returns the expire time of the Multicast Listener. 86 * 87 * @returns The Multicast Listener expire time. 88 * 89 */ GetExpireTime(void) const90 const TimeMilli GetExpireTime(void) const { return mExpireTime; } 91 92 private: SetAddress(const Ip6::Address & aAddress)93 void SetAddress(const Ip6::Address &aAddress) { mAddress = aAddress; } SetExpireTime(TimeMilli aExpireTime)94 void SetExpireTime(TimeMilli aExpireTime) { mExpireTime = aExpireTime; } 95 operator <(const Listener & aOther) const96 bool operator<(const Listener &aOther) const { return GetExpireTime() < aOther.GetExpireTime(); } 97 98 Ip6::Address mAddress; 99 TimeMilli mExpireTime; 100 }; 101 102 /** 103 * This constructor initializes the Multicast Listeners Table. 104 * 105 * @param[in] aInstance A reference to the OpenThread instance. 106 * 107 */ MulticastListenersTable(Instance & aInstance)108 explicit MulticastListenersTable(Instance &aInstance) 109 : InstanceLocator(aInstance) 110 , mNumValidListeners(0) 111 , mCallback(nullptr) 112 , mCallbackContext(nullptr) 113 { 114 } 115 116 /** 117 * This method adds a Multicast Listener with given address and expire time. 118 * 119 * @param[in] aAddress The Multicast Listener address. 120 * @param[in] aExpireTime The Multicast Listener expire time. 121 * 122 * @retval kErrorNone If the Multicast Listener was successfully added. 123 * @retval kErrorInvalidArgs If the Multicast Listener address was invalid. 124 * @retval kErrorNoBufs No space available to save the Multicast Listener. 125 * 126 */ 127 Error Add(const Ip6::Address &aAddress, TimeMilli aExpireTime); 128 129 /** 130 * This method removes a given Multicast Listener. 131 * 132 * @param[in] aAddress The Multicast Listener address. 133 * 134 */ 135 void Remove(const Ip6::Address &aAddress); 136 137 /** 138 * This method removes expired Multicast Listeners. 139 * 140 */ 141 void Expire(void); 142 143 /** 144 * This method counts the number of valid Multicast Listeners. 145 * 146 * @returns The number of valid Multicast Listeners. 147 * 148 */ Count(void) const149 uint16_t Count(void) const { return mNumValidListeners; } 150 151 /** 152 * This method enables range-based `for` loop iteration over all Multicast Listeners. 153 * 154 * This method should be used as follows: 155 * 156 * for (MulticastListenersTable::Listener &listener : Get<MulticastListenersTable>().Iterate()) 157 * 158 * @returns An IteratorBuilder instance. 159 * 160 */ Iterate(void)161 IteratorBuilder Iterate(void) { return IteratorBuilder(GetInstance()); } 162 163 /** 164 * This method removes all the Multicast Listeners. 165 * 166 */ 167 void Clear(void); 168 169 /** 170 * This method sets the Multicast Listener callback. 171 * 172 * @param[in] aCallback The callback function. 173 * @param[in] aContext A user context pointer. 174 * 175 */ 176 void SetCallback(otBackboneRouterMulticastListenerCallback aCallback, void *aContext); 177 178 /** 179 * This method gets the next Multicast Listener. 180 * 181 * @param[in] aIterator A pointer to the Multicast Listener Iterator. 182 * @param[out] aListenerInfo A pointer to where the Multicast Listener info is placed. 183 * 184 * @retval kErrorNone Successfully found the next Multicast Listener info. 185 * @retval kErrorNotFound No subsequent Multicast Listener was found. 186 * 187 */ 188 Error GetNext(otBackboneRouterMulticastListenerIterator &aIterator, 189 otBackboneRouterMulticastListenerInfo & aListenerInfo); 190 191 private: 192 static constexpr uint16_t kMulticastListenersTableSize = OPENTHREAD_CONFIG_MAX_MULTICAST_LISTENERS; 193 194 static_assert( 195 kMulticastListenersTableSize >= 75, 196 "Thread 1.2 Conformance requires the Multicast Listener Table size to be larger than or equal to 75."); 197 198 class IteratorBuilder : InstanceLocator 199 { 200 public: IteratorBuilder(Instance & aInstance)201 explicit IteratorBuilder(Instance &aInstance) 202 : InstanceLocator(aInstance) 203 { 204 } 205 206 Listener *begin(void); 207 Listener *end(void); 208 }; 209 210 void LogMulticastListenersTable(const char * aAction, 211 const Ip6::Address &aAddress, 212 TimeMilli aExpireTime, 213 Error aError); 214 215 void FixHeap(uint16_t aIndex); 216 bool SiftHeapElemDown(uint16_t aIndex); 217 void SiftHeapElemUp(uint16_t aIndex); 218 void CheckInvariants(void) const; 219 220 Listener mListeners[kMulticastListenersTableSize]; 221 uint16_t mNumValidListeners; 222 223 otBackboneRouterMulticastListenerCallback mCallback; 224 void * mCallbackContext; 225 }; 226 227 } // namespace BackboneRouter 228 229 /** 230 * @} 231 */ 232 233 } // namespace ot 234 235 #endif // OPENTHREAD_FTD && OPENTHREAD_CONFIG_BACKBONE_ROUTER_MULTICAST_ROUTING_ENABLE 236 237 #endif // MULTICAST_LISTENERS_TABLE_HPP 238