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