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 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 /** 60 * This struct represents a TREL peer. 61 * 62 */ 63 typedef struct otTrelPeer 64 { 65 otExtAddress mExtAddress; ///< The Extended MAC Address of TREL peer. 66 otExtendedPanId mExtPanId; ///< The Extended PAN Identifier of TREL peer. 67 otSockAddr mSockAddr; ///< The IPv6 socket address of TREL peer. 68 } otTrelPeer; 69 70 /** 71 * This type represents an iterator for iterating over TREL peer table entries. 72 * 73 */ 74 typedef uint16_t otTrelPeerIterator; 75 76 /** 77 * This function enables TREL operation. 78 * 79 * This function initiates an ongoing DNS-SD browse on the service name "_trel._udp" within the local browsing domain 80 * to discover other devices supporting TREL. Device also registers a new service to be advertised using DNS-SD, 81 * with the service name is "_trel._udp" indicating its support for TREL. Device is then ready to receive TREL messages 82 * from peers. 83 * 84 * @note By default the OpenThread stack enables the TREL operation on start. 85 * 86 * @param[in] aInstance The OpenThread instance. 87 * 88 */ 89 void otTrelEnable(otInstance *aInstance); 90 91 /** 92 * This function disables TREL operation. 93 * 94 * This function stops the DNS-SD browse on the service name "_trel._udp", stops advertising TREL DNS-SD service, and 95 * clears the TREL peer table. 96 * 97 * @param[in] aInstance The OpenThread instance. 98 * 99 */ 100 void otTrelDisable(otInstance *aInstance); 101 102 /** 103 * This function indicates whether the TREL operation is enabled. 104 * 105 * @param[in] aInstance The OpenThread instance. 106 * 107 * @retval TRUE if the TREL operation is enabled. 108 * @retval FALSE if the TREL operation is disabled. 109 * 110 */ 111 bool otTrelIsEnabled(otInstance *aInstance); 112 113 /** 114 * This function initializes a peer table iterator. 115 * 116 * @param[in] aInstance The OpenThread instance. 117 * @param[in] aIterator The iterator to initialize. 118 * 119 */ 120 void otTrelInitPeerIterator(otInstance *aInstance, otTrelPeerIterator *aIterator); 121 122 /** 123 * This function iterates over the peer table entries and get the next entry from the table 124 * 125 * @param[in] aInstance The OpenThread instance. 126 * @param[in] aIterator The iterator. MUST be initialized. 127 * 128 * @returns A pointer to the next `otTrelPeer` entry or `NULL` if no more entries in the table. 129 * 130 */ 131 const otTrelPeer *otTrelGetNextPeer(otInstance *aInstance, otTrelPeerIterator *aIterator); 132 133 /** 134 * This function sets the filter mode (enables/disables filtering). 135 * 136 * When filter mode is enabled, any rx and tx traffic through TREL interface is silently dropped. This is mainly 137 * intended for use during testing. 138 * 139 * Unlike `otTrel{Enable/Disable}()` which fully starts/stops the TREL operation, when filter mode is enabled the 140 * TREL interface continues to be enabled. 141 * 142 * @param[in] aInstance The OpenThread instance. 143 * @param[in] aFiltered TRUE to enable filter mode, FALSE to disable filter mode. 144 * 145 */ 146 void otTrelSetFilterEnabled(otInstance *aInstance, bool aEnable); 147 148 /** 149 * This function indicates whether or not the filter mode is enabled. 150 * 151 * @param[in] aInstance The OpenThread instance. 152 * 153 * @retval TRUE if the TREL filter mode is enabled. 154 * @retval FALSE if the TREL filter mode is disabled. 155 * 156 */ 157 bool otTrelIsFilterEnabled(otInstance *aInstance); 158 159 /** 160 * @} 161 * 162 */ 163 164 #ifdef __cplusplus 165 } // extern "C" 166 #endif 167 168 #endif // OPENTHREAD_TREL_H_ 169