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 "coap/coap.hpp" 42 #include "common/locator.hpp" 43 #include "common/non_copyable.hpp" 44 #include "net/ip6_address.hpp" 45 46 namespace ot { 47 48 /** 49 * This class implements Anycast Locator functionality which allows caller to determine the mesh local EID and RLOC16 50 * of the closest destination of an anycast address (if any). 51 * 52 * The closest destination is determined based on the current routing table and path costs within the Thread mesh. 53 * 54 */ 55 class AnycastLocator : public InstanceLocator, private NonCopyable 56 { 57 public: 58 /** 59 * This function pointer type defines the callback to notify the outcome of a request. 60 * 61 */ 62 typedef otThreadAnycastLocatorCallback Callback; 63 64 /** 65 * This constructor initializes the `AnycastLocator` object. 66 * 67 * @param[in] aInstance A reference to the OpenThread instance. 68 * 69 */ 70 explicit AnycastLocator(Instance &aInstance); 71 72 /** 73 * This method 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 */ 87 Error Locate(const Ip6::Address &aAnycastAddress, Callback aCallback, void *aContext); 88 89 /** 90 * This method indicates whether an earlier request is in progress. 91 * 92 * @returns TRUE if an earlier request is in progress, FALSE otherwise. 93 * 94 */ IsInProgress(void) const95 bool IsInProgress(void) const { return (mCallback != nullptr); } 96 97 private: 98 static void HandleResponse(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo, Error aError); 99 100 void HandleResponse(Coap::Message *aMessage, const Ip6::MessageInfo *aMessageInfo, Error aError); 101 102 #if OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_SEND_RESPONSE 103 static void HandleAnycastLocate(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo); 104 void HandleAnycastLocate(const Coap::Message &aRequest, const Ip6::MessageInfo &aMessageInfo); 105 #endif 106 107 Callback mCallback; 108 void * mContext; 109 #if OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_SEND_RESPONSE 110 Coap::Resource mAnycastLocate; 111 #endif 112 }; 113 114 } // namespace ot 115 116 #endif // OPENTHREAD_CONFIG_TMF_ANYCAST_LOCATOR_ENABLE 117 118 #endif // ANYCAST_LOCATOR_HPP_ 119