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 * @brief 32 * This file defines the OpenThread TREL (Thread Radio Encapsulation Link) APIs for Thread Over Infrastructure. 33 * 34 */ 35 36 #ifndef OPENTHREAD_TREL_H_ 37 #define OPENTHREAD_TREL_H_ 38 39 #include <openthread/dataset.h> 40 #include <openthread/ip6.h> 41 #include <openthread/platform/radio.h> 42 #include "openthread/platform/trel.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @addtogroup api-trel 50 * 51 * @brief 52 * This module defines Thread Radio Encapsulation Link (TREL) APIs for Thread Over Infrastructure. 53 * 54 * The functions in this module require `OPENTHREAD_CONFIG_RADIO_LINK_TREL_ENABLE` to be enabled. 55 * 56 * @{ 57 * 58 */ 59 60 /** 61 * Represents a TREL peer. 62 * 63 */ 64 typedef struct otTrelPeer 65 { 66 otExtAddress mExtAddress; ///< The Extended MAC Address of TREL peer. 67 otExtendedPanId mExtPanId; ///< The Extended PAN Identifier of TREL peer. 68 otSockAddr mSockAddr; ///< The IPv6 socket address of TREL peer. 69 } otTrelPeer; 70 71 /** 72 * Represents an iterator for iterating over TREL peer table entries. 73 * 74 */ 75 typedef uint16_t otTrelPeerIterator; 76 77 /** 78 * Enables or disables TREL operation. 79 * 80 * When @p aEnable is true, this function initiates an ongoing DNS-SD browse on the service name "_trel._udp" within the 81 * local browsing domain to discover other devices supporting TREL. Device also registers a new service to be advertised 82 * using DNS-SD, with the service name is "_trel._udp" indicating its support for TREL. Device is then ready to receive 83 * TREL messages from peers. 84 * 85 * When @p aEnable is false, this function stops the DNS-SD browse on the service name "_trel._udp", stops advertising 86 * TREL DNS-SD service, and clears the TREL peer table. 87 * 88 * @note By default the OpenThread stack enables the TREL operation on start. 89 * 90 * @param[in] aInstance A pointer to an OpenThread instance. 91 * @param[in] aEnable A boolean to enable/disable the TREL operation. 92 * 93 */ 94 void otTrelSetEnabled(otInstance *aInstance, bool aEnable); 95 96 /** 97 * Indicates whether the TREL operation is enabled. 98 * 99 * @param[in] aInstance The OpenThread instance. 100 * 101 * @retval TRUE if the TREL operation is enabled. 102 * @retval FALSE if the TREL operation is disabled. 103 * 104 */ 105 bool otTrelIsEnabled(otInstance *aInstance); 106 107 /** 108 * Initializes a peer table iterator. 109 * 110 * @param[in] aInstance The OpenThread instance. 111 * @param[in] aIterator The iterator to initialize. 112 * 113 */ 114 void otTrelInitPeerIterator(otInstance *aInstance, otTrelPeerIterator *aIterator); 115 116 /** 117 * Iterates over the peer table entries and get the next entry from the table 118 * 119 * @param[in] aInstance The OpenThread instance. 120 * @param[in] aIterator The iterator. MUST be initialized. 121 * 122 * @returns A pointer to the next `otTrelPeer` entry or `NULL` if no more entries in the table. 123 * 124 */ 125 const otTrelPeer *otTrelGetNextPeer(otInstance *aInstance, otTrelPeerIterator *aIterator); 126 127 /** 128 * Returns the number of TREL peers. 129 * 130 * @param[in] aInstance A pointer to an OpenThread instance. 131 * 132 * @returns The number of TREL peers. 133 * 134 */ 135 uint16_t otTrelGetNumberOfPeers(otInstance *aInstance); 136 137 /** 138 * Sets the filter mode (enables/disables filtering). 139 * 140 * When filter mode is enabled, any rx and tx traffic through TREL interface is silently dropped. This is mainly 141 * intended for use during testing. 142 * 143 * Unlike `otTrel{Enable/Disable}()` which fully starts/stops the TREL operation, when filter mode is enabled the 144 * TREL interface continues to be enabled. 145 * 146 * @param[in] aInstance The OpenThread instance. 147 * @param[in] aFiltered TRUE to enable filter mode, FALSE to disable filter mode. 148 * 149 */ 150 void otTrelSetFilterEnabled(otInstance *aInstance, bool aEnable); 151 152 /** 153 * Indicates whether or not the filter mode is enabled. 154 * 155 * @param[in] aInstance The OpenThread instance. 156 * 157 * @retval TRUE if the TREL filter mode is enabled. 158 * @retval FALSE if the TREL filter mode is disabled. 159 * 160 */ 161 bool otTrelIsFilterEnabled(otInstance *aInstance); 162 163 /** 164 * Represents a group of TREL related counters. 165 * 166 */ 167 typedef otPlatTrelCounters otTrelCounters; 168 169 /** 170 * Gets the TREL counters. 171 * 172 * @param[in] aInstance A pointer to an OpenThread instance. 173 * 174 * @returns A pointer to the TREL counters. 175 * 176 */ 177 const otTrelCounters *otTrelGetCounters(otInstance *aInstance); 178 179 /** 180 * Resets the TREL counters. 181 * 182 * @param[in] aInstance A pointer to an OpenThread instance. 183 * 184 */ 185 void otTrelResetCounters(otInstance *aInstance); 186 187 /** 188 * @} 189 * 190 */ 191 192 #ifdef __cplusplus 193 } // extern "C" 194 #endif 195 196 #endif // OPENTHREAD_TREL_H_ 197
