1 /* 2 * Copyright (c) 2021, 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 Anycast Locator functionality. 32 */ 33 34 #ifndef ANYCAST_LOCATOR_HPP_ 35 #define ANYCAST_LOCATOR_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #if OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE 40 41 #include "common/callback.hpp" 42 #include "common/locator.hpp" 43 #include "common/non_copyable.hpp" 44 #include "net/ip6_address.hpp" 45 #include "thread/tmf.hpp" 46 47 namespace ot { 48 49 /** 50 * Implements Anycast Locator functionality which allows caller to determine the mesh local EID and RLOC16 51 * of the closest destination of an anycast address (if any). 52 * 53 * The closest destination is determined based on the current routing table and path costs within the Thread mesh. 54 */ 55 class AnycastLocator : public InstanceLocator, private NonCopyable 56 { 57 friend class Tmf::Agent; 58 59 public: 60 /** 61 * Pointer type defines the callback to notify the outcome of a request. 62 */ 63 typedef otThreadAnycastLocatorCallback LocatorCallback; 64 65 /** 66 * Initializes the `AnycastLocator` object. 67 * 68 * @param[in] aInstance A reference to the OpenThread instance. 69 */ 70 explicit AnycastLocator(Instance &aInstance); 71 72 /** 73 * Requests the closest destination of a given anycast address to be located. 74 * 75 * If a previous `Locate()` request is ongoing, a subsequent call to this method will cancel and replace the 76 * earlier request. 77 * 78 * @param[in] aAnycastAddress The anycast address to locate the closest destination of. 79 * @param[in] aCallback The callback handler to report the result. 80 * @param[in] aContext An arbitrary context used with @p aCallback. 81 * 82 * @retval kErrorNone The request started successfully. @p aCallback will be invoked to report the result. 83 * @retval kErrorNoBufs Out of buffers to prepare and send the request message. 84 * @retval kErrorInvalidArgs The @p aAnycastAddress is not a valid anycast address or @p aCallback is `nullptr`. 85 */ 86 Error Locate(const Ip6::Address &aAnycastAddress, LocatorCallback aCallback, void *aContext); 87 88 /** 89 * Indicates whether an earlier request is in progress. 90 * 91 * @returns TRUE if an earlier request is in progress, FALSE otherwise. 92 */ IsInProgress(void) const93 bool IsInProgress(void) const { return mCallback.IsSet(); } 94 95 private: 96 static void HandleResponse(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo, otError aError); 97 98 void HandleResponse(Coap::Message *aMessage, const Ip6::MessageInfo *aMessageInfo, Error aError); 99 100 template <Uri kUri> void HandleTmf(Coap::Message &aMessage, const Ip6::MessageInfo &aMessageInfo); 101 102 Callback<LocatorCallback> mCallback; 103 }; 104 105 #if OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_SEND_RESPONSE 106 DeclareTmfHandler(AnycastLocator, kUriAnycastLocate); 107 #endif 108 109 } // namespace ot 110 111 #endif // OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE 112 113 #endif // ANYCAST_LOCATOR_HPP_ 114