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