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 MLE Discover Scan process. 32 */ 33 34 #ifndef DISCOVER_SCANNER_HPP_ 35 #define DISCOVER_SCANNER_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include "common/locator.hpp" 40 #include "common/non_copyable.hpp" 41 #include "common/timer.hpp" 42 #include "mac/channel_mask.hpp" 43 #include "mac/mac.hpp" 44 #include "mac/mac_types.hpp" 45 #include "meshcop/meshcop.hpp" 46 #include "thread/mle.hpp" 47 48 namespace ot { 49 50 class MeshForwarder; 51 52 namespace Mle { 53 54 /** 55 * This class implements MLE Discover Scan. 56 * 57 */ 58 class DiscoverScanner : public InstanceLocator, private NonCopyable 59 { 60 friend class ot::Instance; 61 friend class ot::MeshForwarder; 62 friend class Mle; 63 64 public: 65 /** 66 * Default scan duration (per channel), in milliseconds. 67 * 68 */ 69 static constexpr uint32_t kDefaultScanDuration = Mac::kScanDurationDefault; 70 71 /** 72 * This type represents Discover Scan result. 73 * 74 */ 75 typedef otActiveScanResult ScanResult; 76 77 /** 78 * This type represents the handler function pointer called with any Discover Scan result or when the scan 79 * completes. 80 * 81 * The handler function format is `void (*oHandler)(ScanResult *aResult, void *aContext);`. End of scan is 82 * indicated by `aResult` pointer being set to `nullptr`. 83 * 84 */ 85 typedef otHandleActiveScanResult Handler; 86 87 /** 88 * This type represents the filter indexes, i.e., hash bit index values for the bloom filter (calculated from a 89 * Joiner ID). 90 * 91 * This is used when filtering is enabled during Discover Scan, i.e., received MLE Discovery Responses with steering 92 * data (bloom filter) not containing the given indexes are filtered. 93 * 94 */ 95 typedef MeshCoP::SteeringData::HashBitIndexes FilterIndexes; 96 97 /** 98 * This constructor initializes the object. 99 * 100 * @param[in] aInstance A reference to the OpenThread instance. 101 * 102 */ 103 explicit DiscoverScanner(Instance &aInstance); 104 105 /** 106 * This method starts a Thread Discovery Scan. 107 * 108 * @param[in] aScanChannels Channel mask listing channels to scan (if empty, use all supported channels). 109 * @param[in] aPanId The PAN ID filter (set to Broadcast PAN to disable filter). 110 * @param[in] aJoiner Value of the Joiner Flag in the Discovery Request TLV. 111 * @param[in] aEnableFiltering Enable filtering MLE Discovery Responses with steering data not containing a 112 * given filter indexes. 113 * @param[in] aFilterIndexes A pointer to `FilterIndexes` to use for filtering (when enabled). 114 * If set to `nullptr`, filter indexes are derived from hash of factory-assigned 115 * EUI64. 116 * @param[in] aCallback A pointer to a function that is called on receiving an MLE Discovery Response. 117 * @param[in] aContext A pointer to arbitrary context information. 118 * 119 * @retval kErrorNone Successfully started a Thread Discovery Scan. 120 * @retval kErrorInvalidState The IPv6 interface is not enabled (netif is not up). 121 * @retval kErrorNoBufs Could not allocate message for Discovery Request. 122 * @retval kErrorBusy Thread Discovery Scan is already in progress. 123 * 124 */ 125 Error Discover(const Mac::ChannelMask &aScanChannels, 126 Mac::PanId aPanId, 127 bool aJoiner, 128 bool aEnableFiltering, 129 const FilterIndexes * aFilterIndexes, 130 Handler aCallback, 131 void * aContext); 132 133 /** 134 * This method indicates whether or not an MLE Thread Discovery Scan is currently in progress. 135 * 136 * @returns true if an MLE Thread Discovery Scan is in progress, false otherwise. 137 * 138 */ IsInProgress(void) const139 bool IsInProgress(void) const { return (mState != kStateIdle); } 140 141 /** 142 * This method sets Joiner Advertisement. 143 * 144 * @param[in] aOui The Vendor OUI for Joiner Advertisement. 145 * @param[in] aAdvData A pointer to AdvData for Joiner Advertisement. 146 * @param[in] aAdvDataLength The length of AdvData. 147 * 148 * @retval kErrorNone Successfully set Joiner Advertisement. 149 * @retval kErrorInvalidArgs Invalid AdvData. 150 * 151 */ 152 Error SetJoinerAdvertisement(uint32_t aOui, const uint8_t *aAdvData, uint8_t aAdvDataLength); 153 154 private: 155 enum State : uint8_t 156 { 157 kStateIdle, 158 kStateScanning, 159 kStateScanDone, 160 }; 161 162 static constexpr uint32_t kMaxOui = 0xffffff; 163 164 // Methods used by `MeshForwarder` 165 Mac::TxFrame *PrepareDiscoveryRequestFrame(Mac::TxFrame &aFrame); 166 void HandleDiscoveryRequestFrameTxDone(Message &aMessage); Stop(void)167 void Stop(void) { HandleDiscoverComplete(); } 168 169 // Methods used from `Mle` 170 void HandleDiscoveryResponse(Mle::RxInfo &aRxInfo) const; 171 172 void HandleDiscoverComplete(void); 173 static void HandleTimer(Timer &aTimer); 174 void HandleTimer(void); 175 176 Handler mHandler; 177 void * mHandlerContext; 178 TimerMilli mTimer; 179 FilterIndexes mFilterIndexes; 180 Mac::ChannelMask mScanChannels; 181 State mState; 182 uint32_t mOui; 183 uint8_t mScanChannel; 184 uint8_t mAdvDataLength; 185 uint8_t mAdvData[MeshCoP::JoinerAdvertisementTlv::kAdvDataMaxLength]; 186 bool mEnableFiltering : 1; 187 bool mShouldRestorePanId : 1; 188 }; 189 190 } // namespace Mle 191 } // namespace ot 192 193 #endif // DISCOVER_SCANNER_HPP_ 194