1 /* 2 * Copyright (c) 2016, 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 UDP API. 33 */ 34 35 #ifndef OPENTHREAD_UDP_H_ 36 #define OPENTHREAD_UDP_H_ 37 38 #include <openthread/ip6.h> 39 #include <openthread/message.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-udp 47 * 48 * @brief 49 * This module includes functions that control UDP communication. 50 * 51 * @{ 52 */ 53 54 /** 55 * This callback allows OpenThread to provide specific handlers for certain UDP messages. 56 * 57 * @retval true The message is handled by this receiver and should not be further processed. 58 * @retval false The message is not handled by this receiver. 59 */ 60 typedef bool (*otUdpHandler)(void *aContext, const otMessage *aMessage, const otMessageInfo *aMessageInfo); 61 62 /** 63 * Represents a UDP receiver. 64 */ 65 typedef struct otUdpReceiver 66 { 67 struct otUdpReceiver *mNext; ///< A pointer to the next UDP receiver (internal use only). 68 otUdpHandler mHandler; ///< A function pointer to the receiver callback. 69 void *mContext; ///< A pointer to application-specific context. 70 } otUdpReceiver; 71 72 /** 73 * Adds a UDP receiver. 74 * 75 * @param[in] aInstance A pointer to an OpenThread instance. 76 * @param[in] aUdpReceiver A pointer to the UDP receiver. 77 * 78 * @retval OT_ERROR_NONE The receiver is successfully added. 79 * @retval OT_ERROR_ALREADY The UDP receiver was already added. 80 */ 81 otError otUdpAddReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver); 82 83 /** 84 * Removes a UDP receiver. 85 * 86 * @param[in] aInstance A pointer to an OpenThread instance. 87 * @param[in] aUdpReceiver A pointer to the UDP receiver. 88 * 89 * @retval OT_ERROR_NONE The receiver is successfully removed. 90 * @retval OT_ERROR_NOT_FOUND The UDP receiver was not added. 91 */ 92 otError otUdpRemoveReceiver(otInstance *aInstance, otUdpReceiver *aUdpReceiver); 93 94 /** 95 * Sends a UDP message without socket. 96 * 97 * @param[in] aInstance A pointer to an OpenThread instance. 98 * @param[in] aMessage A pointer to a message without UDP header. 99 * @param[in] aMessageInfo A pointer to a message info associated with @p aMessage. 100 * 101 * @retval OT_ERROR_NONE Successfully enqueued the message into an output interface. 102 * @retval OT_ERROR_NO_BUFS Insufficient available buffer to add the IPv6 headers. 103 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. 104 */ 105 otError otUdpSendDatagram(otInstance *aInstance, otMessage *aMessage, otMessageInfo *aMessageInfo); 106 107 /** 108 * This callback allows OpenThread to inform the application of a received UDP message. 109 */ 110 typedef void (*otUdpReceive)(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo); 111 112 /** 113 * Defines the OpenThread network interface identifiers. 114 */ 115 typedef enum otNetifIdentifier 116 { 117 OT_NETIF_UNSPECIFIED = 0, ///< Unspecified network interface. 118 OT_NETIF_THREAD_HOST, ///< The host Thread interface - allow use of platform UDP. 119 OT_NETIF_THREAD_INTERNAL, ///< The internal Thread interface (within OpenThread) - do not use platform UDP. 120 OT_NETIF_BACKBONE, ///< The Backbone interface. 121 } otNetifIdentifier; 122 123 /** 124 * Represents a UDP socket. 125 */ 126 typedef struct otUdpSocket 127 { 128 otSockAddr mSockName; ///< The local IPv6 socket address. 129 otSockAddr mPeerName; ///< The peer IPv6 socket address. 130 otUdpReceive mHandler; ///< A function pointer to the application callback. 131 void *mContext; ///< A pointer to application-specific context. 132 void *mHandle; ///< A handle to platform's UDP. 133 struct otUdpSocket *mNext; ///< A pointer to the next UDP socket (internal use only). 134 otNetifIdentifier mNetifId; ///< The network interface identifier. 135 } otUdpSocket; 136 137 /** 138 * Allocate a new message buffer for sending a UDP message. 139 * 140 * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to 141 * OT_MESSAGE_PRIORITY_NORMAL by default. 142 * 143 * @param[in] aInstance A pointer to an OpenThread instance. 144 * @param[in] aSettings A pointer to the message settings or NULL to use default settings. 145 * 146 * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid. 147 * 148 * @sa otMessageFree 149 */ 150 otMessage *otUdpNewMessage(otInstance *aInstance, const otMessageSettings *aSettings); 151 152 /** 153 * Open a UDP/IPv6 socket. 154 * 155 * @param[in] aInstance A pointer to an OpenThread instance. 156 * @param[in] aSocket A pointer to a UDP socket structure. 157 * @param[in] aCallback A pointer to the application callback function. 158 * @param[in] aContext A pointer to application-specific context. 159 * 160 * @retval OT_ERROR_NONE Successfully opened the socket. 161 * @retval OT_ERROR_FAILED Failed to open the socket. 162 */ 163 otError otUdpOpen(otInstance *aInstance, otUdpSocket *aSocket, otUdpReceive aCallback, void *aContext); 164 165 /** 166 * Check if a UDP socket is open. 167 * 168 * @param[in] aInstance A pointer to an OpenThread instance. 169 * @param[in] aSocket A pointer to a UDP socket structure. 170 * 171 * @returns Whether the UDP socket is open. 172 */ 173 bool otUdpIsOpen(otInstance *aInstance, const otUdpSocket *aSocket); 174 175 /** 176 * Close a UDP/IPv6 socket. 177 * 178 * @param[in] aInstance A pointer to an OpenThread instance. 179 * @param[in] aSocket A pointer to a UDP socket structure. 180 * 181 * @retval OT_ERROR_NONE Successfully closed the socket. 182 * @retval OT_ERROR_FAILED Failed to close UDP Socket. 183 */ 184 otError otUdpClose(otInstance *aInstance, otUdpSocket *aSocket); 185 186 /** 187 * Bind a UDP/IPv6 socket. 188 * 189 * @param[in] aInstance A pointer to an OpenThread instance. 190 * @param[in] aSocket A pointer to a UDP socket structure. 191 * @param[in] aSockName A pointer to an IPv6 socket address structure. 192 * @param[in] aNetif The network interface to bind. 193 * 194 * @retval OT_ERROR_NONE Bind operation was successful. 195 * @retval OT_ERROR_FAILED Failed to bind UDP socket. 196 */ 197 otError otUdpBind(otInstance *aInstance, otUdpSocket *aSocket, const otSockAddr *aSockName, otNetifIdentifier aNetif); 198 199 /** 200 * Connect a UDP/IPv6 socket. 201 * 202 * @param[in] aInstance A pointer to an OpenThread instance. 203 * @param[in] aSocket A pointer to a UDP socket structure. 204 * @param[in] aSockName A pointer to an IPv6 socket address structure. 205 * 206 * @retval OT_ERROR_NONE Connect operation was successful. 207 * @retval OT_ERROR_FAILED Failed to connect UDP socket. 208 */ 209 otError otUdpConnect(otInstance *aInstance, otUdpSocket *aSocket, const otSockAddr *aSockName); 210 211 /** 212 * Send a UDP/IPv6 message. 213 * 214 * @param[in] aInstance A pointer to an OpenThread instance. 215 * @param[in] aSocket A pointer to a UDP socket structure. 216 * @param[in] aMessage A pointer to a message buffer. 217 * @param[in] aMessageInfo A pointer to a message info structure. 218 * 219 * If the return value is OT_ERROR_NONE, OpenThread takes ownership of @p aMessage, and the caller should no longer 220 * reference @p aMessage. If the return value is not OT_ERROR_NONE, the caller retains ownership of @p aMessage, 221 * including freeing @p aMessage if the message buffer is no longer needed. 222 * 223 * @retval OT_ERROR_NONE The message is successfully scheduled for sending. 224 * @retval OT_ERROR_INVALID_ARGS Invalid arguments are given. 225 * @retval OT_ERROR_NO_BUFS Insufficient available buffer to add the UDP and IPv6 headers. 226 */ 227 otError otUdpSend(otInstance *aInstance, otUdpSocket *aSocket, otMessage *aMessage, const otMessageInfo *aMessageInfo); 228 229 /** 230 * Gets the head of linked list of UDP Sockets. 231 * 232 * @param[in] aInstance A pointer to an OpenThread instance. 233 * 234 * @returns A pointer to the head of UDP Socket linked list. 235 */ 236 otUdpSocket *otUdpGetSockets(otInstance *aInstance); 237 238 /** 239 * @} 240 */ 241 242 /** 243 * @addtogroup api-udp-forward 244 * 245 * @brief 246 * This module includes functions for UDP forward feature. 247 * 248 * The functions in this module are available when udp-forward feature (`OPENTHREAD_CONFIG_UDP_FORWARD_ENABLE`) is 249 * enabled. 250 * 251 * @{ 252 */ 253 254 /** 255 * Pointer delivers the UDP packet to host and host should send the packet through its own network stack. 256 * 257 * @param[in] aMessage A pointer to the UDP Message. 258 * @param[in] aPeerPort The destination UDP port. 259 * @param[in] aPeerAddr A pointer to the destination IPv6 address. 260 * @param[in] aSockPort The source UDP port. 261 * @param[in] aContext A pointer to application-specific context. 262 */ 263 typedef void (*otUdpForwarder)(otMessage *aMessage, 264 uint16_t aPeerPort, 265 otIp6Address *aPeerAddr, 266 uint16_t aSockPort, 267 void *aContext); 268 269 /** 270 * Set UDP forward callback to deliver UDP packets to host. 271 * 272 * @param[in] aInstance A pointer to an OpenThread instance. 273 * @param[in] aForwarder A pointer to a function called to forward UDP packet to host. 274 * @param[in] aContext A pointer to application-specific context. 275 */ 276 void otUdpForwardSetForwarder(otInstance *aInstance, otUdpForwarder aForwarder, void *aContext); 277 278 /** 279 * Handle a UDP packet received from host. 280 * 281 * @param[in] aInstance A pointer to an OpenThread instance. 282 * @param[in] aMessage A pointer to the UDP Message. 283 * @param[in] aPeerPort The source UDP port. 284 * @param[in] aPeerAddr A pointer to the source address. 285 * @param[in] aSockPort The destination UDP port. 286 * 287 * @warning No matter the call success or fail, the message is freed. 288 */ 289 void otUdpForwardReceive(otInstance *aInstance, 290 otMessage *aMessage, 291 uint16_t aPeerPort, 292 const otIp6Address *aPeerAddr, 293 uint16_t aSockPort); 294 295 /** 296 * Determines if the given UDP port is exclusively opened by OpenThread API. 297 * 298 * @param[in] aInstance A pointer to an OpenThread instance. 299 * @param[in] port UDP port number to verify. 300 * 301 * @retval true The port is being used exclusively by OpenThread. 302 * @retval false The port is not used by any of the OpenThread API or is shared (e.g. is Backbone socket). 303 */ 304 bool otUdpIsPortInUse(otInstance *aInstance, uint16_t port); 305 306 /** 307 * @} 308 */ 309 310 #ifdef __cplusplus 311 } // extern "C" 312 #endif 313 314 #endif // OPENTHREAD_UDP_H_ 315