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