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 IPv6 API. 33 */ 34 35 #ifndef OPENTHREAD_IP6_H_ 36 #define OPENTHREAD_IP6_H_ 37 38 #include <openthread/message.h> 39 #include <openthread/platform/radio.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-ip6 47 * 48 * @brief 49 * This module includes functions that control IPv6 communication. 50 * 51 * @{ 52 * 53 */ 54 55 #define OT_IP6_PREFIX_SIZE 8 ///< Size of an IPv6 prefix (bytes) 56 #define OT_IP6_PREFIX_BITSIZE (OT_IP6_PREFIX_SIZE * 8) ///< Size of an IPv6 prefix (bits) 57 #define OT_IP6_IID_SIZE 8 ///< Size of an IPv6 Interface Identifier (bytes) 58 #define OT_IP6_ADDRESS_SIZE 16 ///< Size of an IPv6 address (bytes) 59 60 /** 61 * @struct otIp6InterfaceIdentifier 62 * 63 * This structure represents the Interface Identifier of an IPv6 address. 64 * 65 */ 66 OT_TOOL_PACKED_BEGIN 67 struct otIp6InterfaceIdentifier 68 { 69 union OT_TOOL_PACKED_FIELD 70 { 71 uint8_t m8[OT_IP6_IID_SIZE]; ///< 8-bit fields 72 uint16_t m16[OT_IP6_IID_SIZE / sizeof(uint16_t)]; ///< 16-bit fields 73 uint32_t m32[OT_IP6_IID_SIZE / sizeof(uint32_t)]; ///< 32-bit fields 74 } mFields; ///< The Interface Identifier accessor fields 75 } OT_TOOL_PACKED_END; 76 77 /** 78 * This structure represents the Interface Identifier of an IPv6 address. 79 * 80 */ 81 typedef struct otIp6InterfaceIdentifier otIp6InterfaceIdentifier; 82 83 /** 84 * @struct otIp6NetworkPrefix 85 * 86 * This structure represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). 87 * 88 */ 89 OT_TOOL_PACKED_BEGIN 90 struct otIp6NetworkPrefix 91 { 92 uint8_t m8[OT_IP6_PREFIX_SIZE]; ///< The Network Prefix. 93 } OT_TOOL_PACKED_END; 94 95 /** 96 * This structure represents the Network Prefix of an IPv6 address (most significant 64 bits of the address). 97 * 98 */ 99 typedef struct otIp6NetworkPrefix otIp6NetworkPrefix; 100 101 /** 102 * @struct otIp6AddressComponents 103 * 104 * This structure represents the components of an IPv6 address. 105 * 106 */ 107 OT_TOOL_PACKED_BEGIN 108 struct otIp6AddressComponents 109 { 110 otIp6NetworkPrefix mNetworkPrefix; ///< The Network Prefix (most significant 64 bits of the address) 111 otIp6InterfaceIdentifier mIid; ///< The Interface Identifier (least significant 64 bits of the address) 112 } OT_TOOL_PACKED_END; 113 114 /** 115 * This structure represents the components of an IPv6 address. 116 * 117 */ 118 typedef struct otIp6AddressComponents otIp6AddressComponents; 119 120 /** 121 * @struct otIp6Address 122 * 123 * This structure represents an IPv6 address. 124 * 125 */ 126 OT_TOOL_PACKED_BEGIN 127 struct otIp6Address 128 { 129 union OT_TOOL_PACKED_FIELD 130 { 131 uint8_t m8[OT_IP6_ADDRESS_SIZE]; ///< 8-bit fields 132 uint16_t m16[OT_IP6_ADDRESS_SIZE / sizeof(uint16_t)]; ///< 16-bit fields 133 uint32_t m32[OT_IP6_ADDRESS_SIZE / sizeof(uint32_t)]; ///< 32-bit fields 134 otIp6AddressComponents mComponents; ///< IPv6 address components 135 } mFields; ///< IPv6 accessor fields 136 } OT_TOOL_PACKED_END; 137 138 /** 139 * This structure represents an IPv6 address. 140 * 141 */ 142 typedef struct otIp6Address otIp6Address; 143 144 /** 145 * This structure represents an IPv6 prefix. 146 * 147 */ 148 OT_TOOL_PACKED_BEGIN 149 struct otIp6Prefix 150 { 151 otIp6Address mPrefix; ///< The IPv6 prefix. 152 uint8_t mLength; ///< The IPv6 prefix length (in bits). 153 } OT_TOOL_PACKED_END; 154 155 /** 156 * This structure represents an IPv6 prefix. 157 * 158 */ 159 typedef struct otIp6Prefix otIp6Prefix; 160 161 /** 162 * IPv6 Address origins 163 * 164 */ 165 enum 166 { 167 OT_ADDRESS_ORIGIN_THREAD = 0, ///< Thread assigned address (ALOC, RLOC, MLEID, etc) 168 OT_ADDRESS_ORIGIN_SLAAC = 1, ///< SLAAC assigned address 169 OT_ADDRESS_ORIGIN_DHCPV6 = 2, ///< DHCPv6 assigned address 170 OT_ADDRESS_ORIGIN_MANUAL = 3, ///< Manually assigned address 171 }; 172 173 /** 174 * This structure represents an IPv6 network interface unicast address. 175 * 176 */ 177 typedef struct otNetifAddress 178 { 179 otIp6Address mAddress; ///< The IPv6 unicast address. 180 uint8_t mPrefixLength; ///< The Prefix length (in bits). 181 uint8_t mAddressOrigin; ///< The IPv6 address origin. 182 bool mPreferred : 1; ///< TRUE if the address is preferred, FALSE otherwise. 183 bool mValid : 1; ///< TRUE if the address is valid, FALSE otherwise. 184 bool mScopeOverrideValid : 1; ///< TRUE if the mScopeOverride value is valid, FALSE otherwise. 185 unsigned int mScopeOverride : 4; ///< The IPv6 scope of this address. 186 bool mRloc : 1; ///< TRUE if the address is an RLOC, FALSE otherwise. 187 struct otNetifAddress *mNext; ///< A pointer to the next network interface address. 188 } otNetifAddress; 189 190 /** 191 * This structure represents an IPv6 network interface multicast address. 192 * 193 */ 194 typedef struct otNetifMulticastAddress 195 { 196 otIp6Address mAddress; ///< The IPv6 multicast address. 197 const struct otNetifMulticastAddress *mNext; ///< A pointer to the next network interface multicast address. 198 } otNetifMulticastAddress; 199 200 /** 201 * This structure represents an IPv6 socket address. 202 * 203 */ 204 typedef struct otSockAddr 205 { 206 otIp6Address mAddress; ///< An IPv6 address. 207 uint16_t mPort; ///< A transport-layer port. 208 } otSockAddr; 209 210 /** 211 * ECN statuses, represented as in the IP header. 212 * 213 */ 214 enum 215 { 216 OT_ECN_NOT_CAPABLE = 0x0, ///< Non-ECT 217 OT_ECN_CAPABLE_0 = 0x2, ///< ECT(0) 218 OT_ECN_CAPABLE_1 = 0x1, ///< ECT(1) 219 OT_ECN_MARKED = 0x3, ///< Congestion encountered (CE) 220 }; 221 222 /** 223 * This structure represents the local and peer IPv6 socket addresses. 224 * 225 */ 226 typedef struct otMessageInfo 227 { 228 otIp6Address mSockAddr; ///< The local IPv6 address. 229 otIp6Address mPeerAddr; ///< The peer IPv6 address. 230 uint16_t mSockPort; ///< The local transport-layer port. 231 uint16_t mPeerPort; ///< The peer transport-layer port. 232 const void * mLinkInfo; ///< A pointer to link-specific information. 233 uint8_t mHopLimit; ///< The IPv6 Hop Limit value. Only applies if `mAllowZeroHopLimit` is FALSE. 234 ///< If `0`, IPv6 Hop Limit is default value `OPENTHREAD_CONFIG_IP6_HOP_LIMIT_DEFAULT`. 235 ///< Otherwise, specifies the IPv6 Hop Limit. 236 uint8_t mEcn : 2; ///< The ECN status of the packet, represented as in the IPv6 header. 237 bool mIsHostInterface : 1; ///< TRUE if packets sent/received via host interface, FALSE otherwise. 238 bool mAllowZeroHopLimit : 1; ///< TRUE to allow IPv6 Hop Limit 0 in `mHopLimit`, FALSE otherwise. 239 bool mMulticastLoop : 1; ///< TRUE to allow looping back multicast, FALSE otherwise. 240 } otMessageInfo; 241 242 /** 243 * Internet Protocol Numbers. 244 * 245 */ 246 enum 247 { 248 OT_IP6_PROTO_HOP_OPTS = 0, ///< IPv6 Hop-by-Hop Option 249 OT_IP6_PROTO_TCP = 6, ///< Transmission Control Protocol 250 OT_IP6_PROTO_UDP = 17, ///< User Datagram 251 OT_IP6_PROTO_IP6 = 41, ///< IPv6 encapsulation 252 OT_IP6_PROTO_ROUTING = 43, ///< Routing Header for IPv6 253 OT_IP6_PROTO_FRAGMENT = 44, ///< Fragment Header for IPv6 254 OT_IP6_PROTO_ICMP6 = 58, ///< ICMP for IPv6 255 OT_IP6_PROTO_NONE = 59, ///< No Next Header for IPv6 256 OT_IP6_PROTO_DST_OPTS = 60, ///< Destination Options for IPv6 257 }; 258 259 /** 260 * This function brings up/down the IPv6 interface. 261 * 262 * Call this function to enable/disable IPv6 communication. 263 * 264 * @param[in] aInstance A pointer to an OpenThread instance. 265 * @param[in] aEnabled TRUE to enable IPv6, FALSE otherwise. 266 * 267 * @retval OT_ERROR_NONE Successfully brought the IPv6 interface up/down. 268 * @retval OT_ERROR_INVALID_STATE IPv6 interface is not available since device is operating in raw-link mode 269 * (applicable only when `OPENTHREAD_CONFIG_LINK_RAW_ENABLE` feature is enabled). 270 * 271 */ 272 otError otIp6SetEnabled(otInstance *aInstance, bool aEnabled); 273 274 /** 275 * This function indicates whether or not the IPv6 interface is up. 276 * 277 * @param[in] aInstance A pointer to an OpenThread instance. 278 * 279 * @retval TRUE The IPv6 interface is enabled. 280 * @retval FALSE The IPv6 interface is disabled. 281 * 282 */ 283 bool otIp6IsEnabled(otInstance *aInstance); 284 285 /** 286 * Add a Network Interface Address to the Thread interface. 287 * 288 * The passed-in instance @p aAddress is copied by the Thread interface. The Thread interface only 289 * supports a fixed number of externally added unicast addresses. See OPENTHREAD_CONFIG_IP6_MAX_EXT_UCAST_ADDRS. 290 * 291 * @param[in] aInstance A pointer to an OpenThread instance. 292 * @param[in] aAddress A pointer to a Network Interface Address. 293 * 294 * @retval OT_ERROR_NONE Successfully added (or updated) the Network Interface Address. 295 * @retval OT_ERROR_INVALID_ARGS The IP Address indicated by @p aAddress is an internal address. 296 * @retval OT_ERROR_NO_BUFS The Network Interface is already storing the maximum allowed external addresses. 297 */ 298 otError otIp6AddUnicastAddress(otInstance *aInstance, const otNetifAddress *aAddress); 299 300 /** 301 * Remove a Network Interface Address from the Thread interface. 302 * 303 * @param[in] aInstance A pointer to an OpenThread instance. 304 * @param[in] aAddress A pointer to an IP Address. 305 * 306 * @retval OT_ERROR_NONE Successfully removed the Network Interface Address. 307 * @retval OT_ERROR_INVALID_ARGS The IP Address indicated by @p aAddress is an internal address. 308 * @retval OT_ERROR_NOT_FOUND The IP Address indicated by @p aAddress was not found. 309 */ 310 otError otIp6RemoveUnicastAddress(otInstance *aInstance, const otIp6Address *aAddress); 311 312 /** 313 * Get the list of IPv6 addresses assigned to the Thread interface. 314 * 315 * @param[in] aInstance A pointer to an OpenThread instance. 316 * 317 * @returns A pointer to the first Network Interface Address. 318 */ 319 const otNetifAddress *otIp6GetUnicastAddresses(otInstance *aInstance); 320 321 /** 322 * Subscribe the Thread interface to a Network Interface Multicast Address. 323 * 324 * The passed in instance @p aAddress will be copied by the Thread interface. The Thread interface only 325 * supports a fixed number of externally added multicast addresses. See OPENTHREAD_CONFIG_IP6_MAX_EXT_MCAST_ADDRS. 326 * 327 * @param[in] aInstance A pointer to an OpenThread instance. 328 * @param[in] aAddress A pointer to an IP Address. 329 * 330 * @retval OT_ERROR_NONE Successfully subscribed to the Network Interface Multicast Address. 331 * @retval OT_ERROR_ALREADY The multicast address is already subscribed. 332 * @retval OT_ERROR_INVALID_ARGS The IP Address indicated by @p aAddress is invalid address. 333 * @retval OT_ERROR_INVALID_STATE The Network Interface is not up. 334 * @retval OT_ERROR_NO_BUFS The Network Interface is already storing the maximum allowed external multicast 335 * addresses. 336 * 337 */ 338 otError otIp6SubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress); 339 340 /** 341 * Unsubscribe the Thread interface to a Network Interface Multicast Address. 342 * 343 * @param[in] aInstance A pointer to an OpenThread instance. 344 * @param[in] aAddress A pointer to an IP Address. 345 * 346 * @retval OT_ERROR_NONE Successfully unsubscribed to the Network Interface Multicast Address. 347 * @retval OT_ERROR_INVALID_ARGS The IP Address indicated by @p aAddress is an internal address. 348 * @retval OT_ERROR_NOT_FOUND The IP Address indicated by @p aAddress was not found. 349 */ 350 otError otIp6UnsubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress); 351 352 /** 353 * Get the list of IPv6 multicast addresses subscribed to the Thread interface. 354 * 355 * @param[in] aInstance A pointer to an OpenThread instance. 356 * 357 * @returns A pointer to the first Network Interface Multicast Address. 358 * 359 */ 360 const otNetifMulticastAddress *otIp6GetMulticastAddresses(otInstance *aInstance); 361 362 /** 363 * Check if multicast promiscuous mode is enabled on the Thread interface. 364 * 365 * @param[in] aInstance A pointer to an OpenThread instance. 366 * 367 * @sa otIp6SetMulticastPromiscuousEnabled 368 * 369 */ 370 bool otIp6IsMulticastPromiscuousEnabled(otInstance *aInstance); 371 372 /** 373 * Enable multicast promiscuous mode on the Thread interface. 374 * 375 * @param[in] aInstance A pointer to an OpenThread instance. 376 * @param[in] aEnabled TRUE to enable Multicast Promiscuous mode, FALSE otherwise. 377 * 378 * @sa otIp6IsMulticastPromiscuousEnabled 379 * 380 */ 381 void otIp6SetMulticastPromiscuousEnabled(otInstance *aInstance, bool aEnabled); 382 383 /** 384 * Allocate a new message buffer for sending an IPv6 message. 385 * 386 * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to 387 * OT_MESSAGE_PRIORITY_NORMAL by default. 388 * 389 * @param[in] aInstance A pointer to an OpenThread instance. 390 * @param[in] aSettings A pointer to the message settings or NULL to set default settings. 391 * 392 * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid. 393 * 394 * @sa otMessageFree 395 * 396 */ 397 otMessage *otIp6NewMessage(otInstance *aInstance, const otMessageSettings *aSettings); 398 399 /** 400 * Allocate a new message buffer and write the IPv6 datagram to the message buffer for sending an IPv6 message. 401 * 402 * @note If @p aSettings is NULL, the link layer security is enabled and the message priority is obtained from IPv6 403 * message itself. 404 * If @p aSettings is not NULL, the @p aSetting->mPriority is ignored and obtained from IPv6 message itself. 405 * 406 * @param[in] aInstance A pointer to an OpenThread instance. 407 * @param[in] aData A pointer to the IPv6 datagram buffer. 408 * @param[in] aDataLength The size of the IPv6 datagram buffer pointed by @p aData. 409 * @param[in] aSettings A pointer to the message settings or NULL to set default settings. 410 * 411 * @returns A pointer to the message or NULL if malformed IPv6 header or insufficient message buffers are available. 412 * 413 * @sa otMessageFree 414 * 415 */ 416 otMessage *otIp6NewMessageFromBuffer(otInstance * aInstance, 417 const uint8_t * aData, 418 uint16_t aDataLength, 419 const otMessageSettings *aSettings); 420 421 /** 422 * This function pointer is called when an IPv6 datagram is received. 423 * 424 * @param[in] aMessage A pointer to the message buffer containing the received IPv6 datagram. This function transfers 425 * the ownership of the @p aMessage to the receiver of the callback. The message should be 426 * freed by the receiver of the callback after it is processed (see otMessageFree()). 427 * @param[in] aContext A pointer to application-specific context. 428 * 429 */ 430 typedef void (*otIp6ReceiveCallback)(otMessage *aMessage, void *aContext); 431 432 /** 433 * This function registers a callback to provide received IPv6 datagrams. 434 * 435 * By default, this callback does not pass Thread control traffic. See otIp6SetReceiveFilterEnabled() to 436 * change the Thread control traffic filter setting. 437 * 438 * @param[in] aInstance A pointer to an OpenThread instance. 439 * @param[in] aCallback A pointer to a function that is called when an IPv6 datagram is received or 440 * NULL to disable the callback. 441 * @param[in] aCallbackContext A pointer to application-specific context. 442 * 443 * @sa otIp6IsReceiveFilterEnabled 444 * @sa otIp6SetReceiveFilterEnabled 445 * 446 */ 447 void otIp6SetReceiveCallback(otInstance *aInstance, otIp6ReceiveCallback aCallback, void *aCallbackContext); 448 449 /** 450 * @struct otIp6AddressInfo 451 * 452 * This structure represents IPv6 address information. 453 * 454 */ 455 typedef struct otIp6AddressInfo 456 { 457 const otIp6Address *mAddress; ///< A pointer to the IPv6 address. 458 uint8_t mPrefixLength; ///< The prefix length of mAddress if it is a unicast address. 459 uint8_t mScope : 4; ///< The scope of this address. 460 bool mPreferred : 1; ///< Whether this is a preferred address. 461 } otIp6AddressInfo; 462 463 /** 464 * This function pointer is called when an internal IPv6 address is added or removed. 465 * 466 * @param[in] aAddressInfo A pointer to the IPv6 address information. 467 * @param[in] aIsAdded TRUE if the @p aAddress was added, FALSE if @p aAddress was removed. 468 * @param[in] aContext A pointer to application-specific context. 469 * 470 */ 471 typedef void (*otIp6AddressCallback)(const otIp6AddressInfo *aAddressInfo, bool aIsAdded, void *aContext); 472 473 /** 474 * This function registers a callback to notify internal IPv6 address changes. 475 * 476 * @param[in] aInstance A pointer to an OpenThread instance. 477 * @param[in] aCallback A pointer to a function that is called when an internal IPv6 address is added or 478 * removed. NULL to disable the callback. 479 * @param[in] aCallbackContext A pointer to application-specific context. 480 * 481 */ 482 void otIp6SetAddressCallback(otInstance *aInstance, otIp6AddressCallback aCallback, void *aCallbackContext); 483 484 /** 485 * This function indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams 486 * via the callback specified in otIp6SetReceiveCallback(). 487 * 488 * @param[in] aInstance A pointer to an OpenThread instance. 489 * 490 * @returns TRUE if Thread control traffic is filtered out, FALSE otherwise. 491 * 492 * @sa otIp6SetReceiveCallback 493 * @sa otIp6SetReceiveFilterEnabled 494 * 495 */ 496 bool otIp6IsReceiveFilterEnabled(otInstance *aInstance); 497 498 /** 499 * This function sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams 500 * via the callback specified in otIp6SetReceiveCallback(). 501 * 502 * @param[in] aInstance A pointer to an OpenThread instance. 503 * @param[in] aEnabled TRUE if Thread control traffic is filtered out, FALSE otherwise. 504 * 505 * @sa otIp6SetReceiveCallback 506 * @sa otIsReceiveIp6FilterEnabled 507 * 508 */ 509 void otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled); 510 511 /** 512 * This function sends an IPv6 datagram via the Thread interface. 513 * 514 * The caller transfers ownership of @p aMessage when making this call. OpenThread will free @p aMessage when 515 * processing is complete, including when a value other than `OT_ERROR_NONE` is returned. 516 * 517 * @param[in] aInstance A pointer to an OpenThread instance. 518 * @param[in] aMessage A pointer to the message buffer containing the IPv6 datagram. 519 * 520 * @retval OT_ERROR_NONE Successfully processed the message. 521 * @retval OT_ERROR_DROP Message was well-formed but not fully processed due to packet processing 522 * rules. 523 * @retval OT_ERROR_NO_BUFS Could not allocate necessary message buffers when processing the datagram. 524 * @retval OT_ERROR_NO_ROUTE No route to host. 525 * @retval OT_ERROR_INVALID_SOURCE_ADDRESS Source address is invalid, e.g. an anycast address or a multicast address. 526 * @retval OT_ERROR_PARSE Encountered a malformed header when processing the message. 527 * 528 */ 529 otError otIp6Send(otInstance *aInstance, otMessage *aMessage); 530 531 /** 532 * This function adds a port to the allowed unsecured port list. 533 * 534 * @param[in] aInstance A pointer to an OpenThread instance. 535 * @param[in] aPort The port value. 536 * 537 * @retval OT_ERROR_NONE The port was successfully added to the allowed unsecure port list. 538 * @retval OT_ERROR_INVALID_ARGS The port is invalid (value 0 is reserved for internal use). 539 * @retval OT_ERROR_NO_BUFS The unsecure port list is full. 540 * 541 */ 542 otError otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort); 543 544 /** 545 * This function removes a port from the allowed unsecure port list. 546 * 547 * @note This function removes @p aPort by overwriting @p aPort with the element after @p aPort in the internal port 548 * list. Be careful when calling otIp6GetUnsecurePorts() followed by otIp6RemoveUnsecurePort() to remove unsecure 549 * ports. 550 * 551 * @param[in] aInstance A pointer to an OpenThread instance. 552 * @param[in] aPort The port value. 553 * 554 * @retval OT_ERROR_NONE The port was successfully removed from the allowed unsecure port list. 555 * @retval OT_ERROR_INVALID_ARGS The port is invalid (value 0 is reserved for internal use). 556 * @retval OT_ERROR_NOT_FOUND The port was not found in the unsecure port list. 557 * 558 */ 559 otError otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort); 560 561 /** 562 * This function removes all ports from the allowed unsecure port list. 563 * 564 * @param[in] aInstance A pointer to an OpenThread instance. 565 * 566 */ 567 void otIp6RemoveAllUnsecurePorts(otInstance *aInstance); 568 569 /** 570 * This function returns a pointer to the unsecure port list. 571 * 572 * @note Port value 0 is used to indicate an invalid entry. 573 * 574 * @param[in] aInstance A pointer to an OpenThread instance. 575 * @param[out] aNumEntries The number of entries in the list. 576 * 577 * @returns A pointer to the unsecure port list. 578 * 579 */ 580 const uint16_t *otIp6GetUnsecurePorts(otInstance *aInstance, uint8_t *aNumEntries); 581 582 /** 583 * Test if two IPv6 addresses are the same. 584 * 585 * @param[in] aFirst A pointer to the first IPv6 address to compare. 586 * @param[in] aSecond A pointer to the second IPv6 address to compare. 587 * 588 * @retval TRUE The two IPv6 addresses are the same. 589 * @retval FALSE The two IPv6 addresses are not the same. 590 * 591 */ 592 bool otIp6IsAddressEqual(const otIp6Address *aFirst, const otIp6Address *aSecond); 593 594 /** 595 * Test if two IPv6 prefixes are the same. 596 * 597 * @param[in] aFirst A pointer to the first IPv6 prefix to compare. 598 * @param[in] aSecond A pointer to the second IPv6 prefix to compare. 599 * 600 * @retval TRUE The two IPv6 prefixes are the same. 601 * @retval FALSE The two IPv6 prefixes are not the same. 602 * 603 */ 604 bool otIp6ArePrefixesEqual(const otIp6Prefix *aFirst, const otIp6Prefix *aSecond); 605 606 /** 607 * This function converts a human-readable IPv6 address string into a binary representation. 608 * 609 * @param[in] aString A pointer to a NULL-terminated string. 610 * @param[out] aAddress A pointer to an IPv6 address. 611 * 612 * @retval OT_ERROR_NONE Successfully parsed the string. 613 * @retval OT_ERROR_INVALID_ARGS Failed to parse the string. 614 * 615 */ 616 otError otIp6AddressFromString(const char *aString, otIp6Address *aAddress); 617 618 #define OT_IP6_ADDRESS_STRING_SIZE 40 ///< Recommended size for string representation of an IPv6 address. 619 620 /** 621 * This function converts a given IPv6 address to a human-readable string. 622 * 623 * The IPv6 address string is formatted as 16 hex values separated by ':' (i.e., "%x:%x:%x:...:%x"). 624 * 625 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 626 * but the outputted string is always null-terminated. 627 * 628 * @param[in] aAddress A pointer to an IPv6 address (MUST NOT be NULL). 629 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 630 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_ADDRESS_STRING_SIZE`. 631 * 632 */ 633 void otIp6AddressToString(const otIp6Address *aAddress, char *aBuffer, uint16_t aSize); 634 635 #define OT_IP6_SOCK_ADDR_STRING_SIZE 48 ///< Recommended size for string representation of an IPv6 socket address. 636 637 /** 638 * This function converts a given IPv6 socket address to a human-readable string. 639 * 640 * The IPv6 socket address string is formatted as "[<address>]:<port>" where `<address> is shown as 16 hex values 641 * separated by ':' and `<port>` is the port number in decimal format (i.e., "[%x:%x:...:%x]:%u") 642 * 643 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 644 * but the outputted string is always null-terminated. 645 * 646 * @param[in] aSockAddr A pointer to an IPv6 socket address (MUST NOT be NULL). 647 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 648 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_SOCK_ADDR_STRING_SIZE`. 649 * 650 */ 651 void otIp6SockAddrToString(const otSockAddr *aSockAddr, char *aBuffer, uint16_t aSize); 652 653 #define OT_IP6_PREFIX_STRING_SIZE 45 ///< Recommended size for string representation of an IPv6 prefix. 654 655 /** 656 * This function converts a given IPv6 prefix to a human-readable string. 657 * 658 * The IPv6 address string is formatted as "%x:%x:%x:...[::]/plen". 659 * 660 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 661 * but the outputted string is always null-terminated. 662 * 663 * @param[in] aPrefix A pointer to an IPv6 prefix (MUST NOT be NULL). 664 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 665 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_PREFIX_STRING_SIZE`. 666 * 667 */ 668 void otIp6PrefixToString(const otIp6Prefix *aPrefix, char *aBuffer, uint16_t aSize); 669 670 /** 671 * This function returns the prefix match length (bits) for two IPv6 addresses. 672 * 673 * @param[in] aFirst A pointer to the first IPv6 address. 674 * @param[in] aSecond A pointer to the second IPv6 address. 675 * 676 * @returns The prefix match length in bits. 677 * 678 */ 679 uint8_t otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond); 680 681 /** 682 * This function indicates whether or not a given IPv6 address is the Unspecified Address. 683 * 684 * @param[in] aAddress A pointer to an IPv6 address. 685 * 686 * @retval TRUE If the IPv6 address is the Unspecified Address. 687 * @retval FALSE If the IPv6 address is not the Unspecified Address. 688 * 689 */ 690 bool otIp6IsAddressUnspecified(const otIp6Address *aAddress); 691 692 /** 693 * This function perform OpenThread source address selection. 694 * 695 * @param[in] aInstance A pointer to an OpenThread instance. 696 * @param[inout] aMessageInfo A pointer to the message information. 697 * 698 * @retval OT_ERROR_NONE Found a source address and is filled into mSockAddr of @p aMessageInfo. 699 * @retval OT_ERROR_NOT_FOUND No source address was found and @p aMessageInfo is unchanged. 700 * 701 */ 702 otError otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageInfo); 703 704 /** 705 * This function indicates whether the SLAAC module is enabled or not. 706 * 707 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 708 * 709 * @retval TRUE SLAAC module is enabled. 710 * @retval FALSE SLAAC module is disabled. 711 * 712 */ 713 bool otIp6IsSlaacEnabled(otInstance *aInstance); 714 715 /** 716 * This function enables/disables the SLAAC module. 717 * 718 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 719 * 720 * When SLAAC module is enabled, SLAAC addresses (based on on-mesh prefixes in Network Data) are added to the interface. 721 * When SLAAC module is disabled any previously added SLAAC address is removed. 722 * 723 * @param[in] aInstance A pointer to an OpenThread instance. 724 * @param[in] aEnabled TRUE to enable, FALSE to disable. 725 * 726 */ 727 void otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled); 728 729 /** 730 * This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added. 731 * 732 * `otIp6SetSlaacPrefixFilter()` can be used to set the filter handler. The filter handler is invoked by SLAAC module 733 * when it is about to add a SLAAC address based on a prefix. Its boolean return value determines whether the address 734 * is filtered (not added) or not. 735 * 736 * @param[in] aInstacne A pointer to an OpenThread instance. 737 * @param[in] aPrefix A pointer to prefix for which SLAAC address is about to be added. 738 * 739 * @retval TRUE Indicates that the SLAAC address based on the prefix should be filtered and NOT added. 740 * @retval FALSE Indicates that the SLAAC address based on the prefix should be added. 741 * 742 */ 743 typedef bool (*otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix); 744 745 /** 746 * This function sets the SLAAC module filter handler. 747 * 748 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 749 * 750 * The filter handler is called by SLAAC module when it is about to add a SLAAC address based on a prefix to decide 751 * whether the address should be added or not. 752 * 753 * A NULL filter handler disables filtering and allows all SLAAC addresses to be added. 754 * 755 * If this function is not called, the default filter used by SLAAC module will be NULL (filtering is disabled). 756 * 757 * @param[in] aInstance A pointer to an OpenThread instance. 758 * @param[in] aFilter A pointer to SLAAC prefix filter handler, or NULL to disable filtering. 759 * 760 */ 761 void otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter); 762 763 /** 764 * This function pointer is called with results of `otIp6RegisterMulticastListeners`. 765 * 766 * @param[in] aContext A pointer to the user context. 767 * @param[in] aError OT_ERROR_NONE when successfully sent MLR.req and received MLR.rsp, 768 * OT_ERROR_RESPONSE_TIMEOUT when failed to receive MLR.rsp, 769 * OT_ERROR_PARSE when failed to parse MLR.rsp. 770 * @param[in] aMlrStatus The Multicast Listener Registration status when @p aError is OT_ERROR_NONE. 771 * @param[in] aFailedAddresses A pointer to the failed IPv6 addresses when @p aError is OT_ERROR_NONE. 772 * @param[in] aFailedAddressNum The number of failed IPv6 addresses when @p aError is OT_ERROR_NONE. 773 * 774 * @sa otIp6RegisterMulticastListeners 775 * 776 */ 777 typedef void (*otIp6RegisterMulticastListenersCallback)(void * aContext, 778 otError aError, 779 uint8_t aMlrStatus, 780 const otIp6Address *aFailedAddresses, 781 uint8_t aFailedAddressNum); 782 783 /** 784 * This function registers Multicast Listeners to Primary Backbone Router. 785 * 786 * Note: only available when both `OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE` and 787 * `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` are enabled) 788 * 789 * @param[in] aInstance A pointer to an OpenThread instance. 790 * @param[in] aAddresses A Multicast Address Array to register. 791 * @param[in] aAddressNum The number of Multicast Address to register (0 if @p aAddresses is NULL). 792 * @param[in] aTimeout A pointer to the timeout value (in seconds) to be included in MLR.req. A timeout value of 0 793 * removes the corresponding Multicast Listener. If NULL, MLR.req would have no Timeout Tlv by 794 * default. 795 * @param[in] aCallback A pointer to the callback function. 796 * @param[in] aContext A pointer to the user context. 797 * 798 * @retval OT_ERROR_NONE Successfully sent MLR.req. The @p aCallback will be called iff this method 799 * returns OT_ERROR_NONE. 800 * @retval OT_ERROR_BUSY If a previous registration was ongoing. 801 * @retval OT_ERROR_INVALID_ARGS If one or more arguments are invalid. 802 * @retval OT_ERROR_INVALID_STATE If the device was not in a valid state to send MLR.req (e.g. Commissioner not 803 * started, Primary Backbone Router not found). 804 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 805 * 806 * @sa otIp6RegisterMulticastListenersCallback 807 * 808 */ 809 otError otIp6RegisterMulticastListeners(otInstance * aInstance, 810 const otIp6Address * aAddresses, 811 uint8_t aAddressNum, 812 const uint32_t * aTimeout, 813 otIp6RegisterMulticastListenersCallback aCallback, 814 void * aContext); 815 816 /** 817 * This function sets the Mesh Local IID (for test purpose). 818 * 819 * Only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 820 * 821 * @param[in] aInstance A pointer to an OpenThread instance. 822 * @param[in] aIid A pointer to the Mesh Local IID to set. 823 * 824 * @retval OT_ERROR_NONE Successfully set the Mesh Local IID. 825 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 826 * 827 */ 828 otError otIp6SetMeshLocalIid(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 829 830 /** 831 * This function converts a given IP protocol number to a human-readable string. 832 * 833 * @param[in] aIpProto An IP protocol number (`OT_IP6_PROTO_*` enumeration). 834 * 835 * @returns A string representing @p aIpProto. 836 * 837 */ 838 const char *otIp6ProtoToString(uint8_t aIpProto); 839 840 /** 841 * @} 842 * 843 */ 844 845 #ifdef __cplusplus 846 } // extern "C" 847 #endif 848 849 #endif // OPENTHREAD_IP6_H_ 850
