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