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 an invalid multicast address. 333 * @retval OT_ERROR_REJECTED The IP Address indicated by @p aAddress is an internal multicast address. 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_REJECTED 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 */ 351 otError otIp6UnsubscribeMulticastAddress(otInstance *aInstance, const otIp6Address *aAddress); 352 353 /** 354 * Get the list of IPv6 multicast addresses subscribed to the Thread interface. 355 * 356 * @param[in] aInstance A pointer to an OpenThread instance. 357 * 358 * @returns A pointer to the first Network Interface Multicast Address. 359 * 360 */ 361 const otNetifMulticastAddress *otIp6GetMulticastAddresses(otInstance *aInstance); 362 363 /** 364 * Check if multicast promiscuous mode is enabled on the Thread interface. 365 * 366 * @param[in] aInstance A pointer to an OpenThread instance. 367 * 368 * @sa otIp6SetMulticastPromiscuousEnabled 369 * 370 */ 371 bool otIp6IsMulticastPromiscuousEnabled(otInstance *aInstance); 372 373 /** 374 * Enable multicast promiscuous mode on the Thread interface. 375 * 376 * @param[in] aInstance A pointer to an OpenThread instance. 377 * @param[in] aEnabled TRUE to enable Multicast Promiscuous mode, FALSE otherwise. 378 * 379 * @sa otIp6IsMulticastPromiscuousEnabled 380 * 381 */ 382 void otIp6SetMulticastPromiscuousEnabled(otInstance *aInstance, bool aEnabled); 383 384 /** 385 * Allocate a new message buffer for sending an IPv6 message. 386 * 387 * @note If @p aSettings is 'NULL', the link layer security is enabled and the message priority is set to 388 * OT_MESSAGE_PRIORITY_NORMAL by default. 389 * 390 * @param[in] aInstance A pointer to an OpenThread instance. 391 * @param[in] aSettings A pointer to the message settings or NULL to set default settings. 392 * 393 * @returns A pointer to the message buffer or NULL if no message buffers are available or parameters are invalid. 394 * 395 * @sa otMessageFree 396 * 397 */ 398 otMessage *otIp6NewMessage(otInstance *aInstance, const otMessageSettings *aSettings); 399 400 /** 401 * Allocate a new message buffer and write the IPv6 datagram to the message buffer for sending an IPv6 message. 402 * 403 * @note If @p aSettings is NULL, the link layer security is enabled and the message priority is obtained from IPv6 404 * message itself. 405 * If @p aSettings is not NULL, the @p aSetting->mPriority is ignored and obtained from IPv6 message itself. 406 * 407 * @param[in] aInstance A pointer to an OpenThread instance. 408 * @param[in] aData A pointer to the IPv6 datagram buffer. 409 * @param[in] aDataLength The size of the IPv6 datagram buffer pointed by @p aData. 410 * @param[in] aSettings A pointer to the message settings or NULL to set default settings. 411 * 412 * @returns A pointer to the message or NULL if malformed IPv6 header or insufficient message buffers are available. 413 * 414 * @sa otMessageFree 415 * 416 */ 417 otMessage *otIp6NewMessageFromBuffer(otInstance * aInstance, 418 const uint8_t * aData, 419 uint16_t aDataLength, 420 const otMessageSettings *aSettings); 421 422 /** 423 * This function pointer is called when an IPv6 datagram is received. 424 * 425 * @param[in] aMessage A pointer to the message buffer containing the received IPv6 datagram. This function transfers 426 * the ownership of the @p aMessage to the receiver of the callback. The message should be 427 * freed by the receiver of the callback after it is processed (see otMessageFree()). 428 * @param[in] aContext A pointer to application-specific context. 429 * 430 */ 431 typedef void (*otIp6ReceiveCallback)(otMessage *aMessage, void *aContext); 432 433 /** 434 * This function registers a callback to provide received IPv6 datagrams. 435 * 436 * By default, this callback does not pass Thread control traffic. See otIp6SetReceiveFilterEnabled() to 437 * change the Thread control traffic filter setting. 438 * 439 * @param[in] aInstance A pointer to an OpenThread instance. 440 * @param[in] aCallback A pointer to a function that is called when an IPv6 datagram is received or 441 * NULL to disable the callback. 442 * @param[in] aCallbackContext A pointer to application-specific context. 443 * 444 * @sa otIp6IsReceiveFilterEnabled 445 * @sa otIp6SetReceiveFilterEnabled 446 * 447 */ 448 void otIp6SetReceiveCallback(otInstance *aInstance, otIp6ReceiveCallback aCallback, void *aCallbackContext); 449 450 /** 451 * @struct otIp6AddressInfo 452 * 453 * This structure represents IPv6 address information. 454 * 455 */ 456 typedef struct otIp6AddressInfo 457 { 458 const otIp6Address *mAddress; ///< A pointer to the IPv6 address. 459 uint8_t mPrefixLength; ///< The prefix length of mAddress if it is a unicast address. 460 uint8_t mScope : 4; ///< The scope of this address. 461 bool mPreferred : 1; ///< Whether this is a preferred address. 462 } otIp6AddressInfo; 463 464 /** 465 * This function pointer is called when an internal IPv6 address is added or removed. 466 * 467 * @param[in] aAddressInfo A pointer to the IPv6 address information. 468 * @param[in] aIsAdded TRUE if the @p aAddress was added, FALSE if @p aAddress was removed. 469 * @param[in] aContext A pointer to application-specific context. 470 * 471 */ 472 typedef void (*otIp6AddressCallback)(const otIp6AddressInfo *aAddressInfo, bool aIsAdded, void *aContext); 473 474 /** 475 * This function registers a callback to notify internal IPv6 address changes. 476 * 477 * @param[in] aInstance A pointer to an OpenThread instance. 478 * @param[in] aCallback A pointer to a function that is called when an internal IPv6 address is added or 479 * removed. NULL to disable the callback. 480 * @param[in] aCallbackContext A pointer to application-specific context. 481 * 482 */ 483 void otIp6SetAddressCallback(otInstance *aInstance, otIp6AddressCallback aCallback, void *aCallbackContext); 484 485 /** 486 * This function indicates whether or not Thread control traffic is filtered out when delivering IPv6 datagrams 487 * via the callback specified in otIp6SetReceiveCallback(). 488 * 489 * @param[in] aInstance A pointer to an OpenThread instance. 490 * 491 * @returns TRUE if Thread control traffic is filtered out, FALSE otherwise. 492 * 493 * @sa otIp6SetReceiveCallback 494 * @sa otIp6SetReceiveFilterEnabled 495 * 496 */ 497 bool otIp6IsReceiveFilterEnabled(otInstance *aInstance); 498 499 /** 500 * This function sets whether or not Thread control traffic is filtered out when delivering IPv6 datagrams 501 * via the callback specified in otIp6SetReceiveCallback(). 502 * 503 * @param[in] aInstance A pointer to an OpenThread instance. 504 * @param[in] aEnabled TRUE if Thread control traffic is filtered out, FALSE otherwise. 505 * 506 * @sa otIp6SetReceiveCallback 507 * @sa otIsReceiveIp6FilterEnabled 508 * 509 */ 510 void otIp6SetReceiveFilterEnabled(otInstance *aInstance, bool aEnabled); 511 512 /** 513 * This function sends an IPv6 datagram via the Thread interface. 514 * 515 * The caller transfers ownership of @p aMessage when making this call. OpenThread will free @p aMessage when 516 * processing is complete, including when a value other than `OT_ERROR_NONE` is returned. 517 * 518 * @param[in] aInstance A pointer to an OpenThread instance. 519 * @param[in] aMessage A pointer to the message buffer containing the IPv6 datagram. 520 * 521 * @retval OT_ERROR_NONE Successfully processed the message. 522 * @retval OT_ERROR_DROP Message was well-formed but not fully processed due to packet processing 523 * rules. 524 * @retval OT_ERROR_NO_BUFS Could not allocate necessary message buffers when processing the datagram. 525 * @retval OT_ERROR_NO_ROUTE No route to host. 526 * @retval OT_ERROR_INVALID_SOURCE_ADDRESS Source address is invalid, e.g. an anycast address or a multicast address. 527 * @retval OT_ERROR_PARSE Encountered a malformed header when processing the message. 528 * 529 */ 530 otError otIp6Send(otInstance *aInstance, otMessage *aMessage); 531 532 /** 533 * This function adds a port to the allowed unsecured port list. 534 * 535 * @param[in] aInstance A pointer to an OpenThread instance. 536 * @param[in] aPort The port value. 537 * 538 * @retval OT_ERROR_NONE The port was successfully added to the allowed unsecure port list. 539 * @retval OT_ERROR_INVALID_ARGS The port is invalid (value 0 is reserved for internal use). 540 * @retval OT_ERROR_NO_BUFS The unsecure port list is full. 541 * 542 */ 543 otError otIp6AddUnsecurePort(otInstance *aInstance, uint16_t aPort); 544 545 /** 546 * This function removes a port from the allowed unsecure port list. 547 * 548 * @note This function removes @p aPort by overwriting @p aPort with the element after @p aPort in the internal port 549 * list. Be careful when calling otIp6GetUnsecurePorts() followed by otIp6RemoveUnsecurePort() to remove unsecure 550 * ports. 551 * 552 * @param[in] aInstance A pointer to an OpenThread instance. 553 * @param[in] aPort The port value. 554 * 555 * @retval OT_ERROR_NONE The port was successfully removed from the allowed unsecure port list. 556 * @retval OT_ERROR_INVALID_ARGS The port is invalid (value 0 is reserved for internal use). 557 * @retval OT_ERROR_NOT_FOUND The port was not found in the unsecure port list. 558 * 559 */ 560 otError otIp6RemoveUnsecurePort(otInstance *aInstance, uint16_t aPort); 561 562 /** 563 * This function removes all ports from the allowed unsecure port list. 564 * 565 * @param[in] aInstance A pointer to an OpenThread instance. 566 * 567 */ 568 void otIp6RemoveAllUnsecurePorts(otInstance *aInstance); 569 570 /** 571 * This function returns a pointer to the unsecure port list. 572 * 573 * @note Port value 0 is used to indicate an invalid entry. 574 * 575 * @param[in] aInstance A pointer to an OpenThread instance. 576 * @param[out] aNumEntries The number of entries in the list. 577 * 578 * @returns A pointer to the unsecure port list. 579 * 580 */ 581 const uint16_t *otIp6GetUnsecurePorts(otInstance *aInstance, uint8_t *aNumEntries); 582 583 /** 584 * Test if two IPv6 addresses are the same. 585 * 586 * @param[in] aFirst A pointer to the first IPv6 address to compare. 587 * @param[in] aSecond A pointer to the second IPv6 address to compare. 588 * 589 * @retval TRUE The two IPv6 addresses are the same. 590 * @retval FALSE The two IPv6 addresses are not the same. 591 * 592 */ 593 bool otIp6IsAddressEqual(const otIp6Address *aFirst, const otIp6Address *aSecond); 594 595 /** 596 * Test if two IPv6 prefixes are the same. 597 * 598 * @param[in] aFirst A pointer to the first IPv6 prefix to compare. 599 * @param[in] aSecond A pointer to the second IPv6 prefix to compare. 600 * 601 * @retval TRUE The two IPv6 prefixes are the same. 602 * @retval FALSE The two IPv6 prefixes are not the same. 603 * 604 */ 605 bool otIp6ArePrefixesEqual(const otIp6Prefix *aFirst, const otIp6Prefix *aSecond); 606 607 /** 608 * This function converts a human-readable IPv6 address string into a binary representation. 609 * 610 * @param[in] aString A pointer to a NULL-terminated string. 611 * @param[out] aAddress A pointer to an IPv6 address. 612 * 613 * @retval OT_ERROR_NONE Successfully parsed the string. 614 * @retval OT_ERROR_INVALID_ARGS Failed to parse the string. 615 * 616 */ 617 otError otIp6AddressFromString(const char *aString, otIp6Address *aAddress); 618 619 #define OT_IP6_ADDRESS_STRING_SIZE 40 ///< Recommended size for string representation of an IPv6 address. 620 621 /** 622 * This function converts a given IPv6 address to a human-readable string. 623 * 624 * The IPv6 address string is formatted as 16 hex values separated by ':' (i.e., "%x:%x:%x:...:%x"). 625 * 626 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 627 * but the outputted string is always null-terminated. 628 * 629 * @param[in] aAddress A pointer to an IPv6 address (MUST NOT be NULL). 630 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 631 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_ADDRESS_STRING_SIZE`. 632 * 633 */ 634 void otIp6AddressToString(const otIp6Address *aAddress, char *aBuffer, uint16_t aSize); 635 636 #define OT_IP6_SOCK_ADDR_STRING_SIZE 48 ///< Recommended size for string representation of an IPv6 socket address. 637 638 /** 639 * This function converts a given IPv6 socket address to a human-readable string. 640 * 641 * The IPv6 socket address string is formatted as "[<address>]:<port>" where `<address> is shown as 16 hex values 642 * separated by ':' and `<port>` is the port number in decimal format (i.e., "[%x:%x:...:%x]:%u") 643 * 644 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 645 * but the outputted string is always null-terminated. 646 * 647 * @param[in] aSockAddr A pointer to an IPv6 socket address (MUST NOT be NULL). 648 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 649 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_SOCK_ADDR_STRING_SIZE`. 650 * 651 */ 652 void otIp6SockAddrToString(const otSockAddr *aSockAddr, char *aBuffer, uint16_t aSize); 653 654 #define OT_IP6_PREFIX_STRING_SIZE 45 ///< Recommended size for string representation of an IPv6 prefix. 655 656 /** 657 * This function converts a given IPv6 prefix to a human-readable string. 658 * 659 * The IPv6 address string is formatted as "%x:%x:%x:...[::]/plen". 660 * 661 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 662 * but the outputted string is always null-terminated. 663 * 664 * @param[in] aPrefix A pointer to an IPv6 prefix (MUST NOT be NULL). 665 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 666 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_PREFIX_STRING_SIZE`. 667 * 668 */ 669 void otIp6PrefixToString(const otIp6Prefix *aPrefix, char *aBuffer, uint16_t aSize); 670 671 /** 672 * This function returns the prefix match length (bits) for two IPv6 addresses. 673 * 674 * @param[in] aFirst A pointer to the first IPv6 address. 675 * @param[in] aSecond A pointer to the second IPv6 address. 676 * 677 * @returns The prefix match length in bits. 678 * 679 */ 680 uint8_t otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond); 681 682 /** 683 * This function indicates whether or not a given IPv6 address is the Unspecified Address. 684 * 685 * @param[in] aAddress A pointer to an IPv6 address. 686 * 687 * @retval TRUE If the IPv6 address is the Unspecified Address. 688 * @retval FALSE If the IPv6 address is not the Unspecified Address. 689 * 690 */ 691 bool otIp6IsAddressUnspecified(const otIp6Address *aAddress); 692 693 /** 694 * This function perform OpenThread source address selection. 695 * 696 * @param[in] aInstance A pointer to an OpenThread instance. 697 * @param[in,out] aMessageInfo A pointer to the message information. 698 * 699 * @retval OT_ERROR_NONE Found a source address and is filled into mSockAddr of @p aMessageInfo. 700 * @retval OT_ERROR_NOT_FOUND No source address was found and @p aMessageInfo is unchanged. 701 * 702 */ 703 otError otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageInfo); 704 705 /** 706 * This function indicates whether the SLAAC module is enabled or not. 707 * 708 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 709 * 710 * @retval TRUE SLAAC module is enabled. 711 * @retval FALSE SLAAC module is disabled. 712 * 713 */ 714 bool otIp6IsSlaacEnabled(otInstance *aInstance); 715 716 /** 717 * This function enables/disables the SLAAC module. 718 * 719 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 720 * 721 * When SLAAC module is enabled, SLAAC addresses (based on on-mesh prefixes in Network Data) are added to the interface. 722 * When SLAAC module is disabled any previously added SLAAC address is removed. 723 * 724 * @param[in] aInstance A pointer to an OpenThread instance. 725 * @param[in] aEnabled TRUE to enable, FALSE to disable. 726 * 727 */ 728 void otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled); 729 730 /** 731 * This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added. 732 * 733 * `otIp6SetSlaacPrefixFilter()` can be used to set the filter handler. The filter handler is invoked by SLAAC module 734 * when it is about to add a SLAAC address based on a prefix. Its boolean return value determines whether the address 735 * is filtered (not added) or not. 736 * 737 * @param[in] aInstance A pointer to an OpenThread instance. 738 * @param[in] aPrefix A pointer to prefix for which SLAAC address is about to be added. 739 * 740 * @retval TRUE Indicates that the SLAAC address based on the prefix should be filtered and NOT added. 741 * @retval FALSE Indicates that the SLAAC address based on the prefix should be added. 742 * 743 */ 744 typedef bool (*otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix); 745 746 /** 747 * This function sets the SLAAC module filter handler. 748 * 749 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 750 * 751 * The filter handler is called by SLAAC module when it is about to add a SLAAC address based on a prefix to decide 752 * whether the address should be added or not. 753 * 754 * A NULL filter handler disables filtering and allows all SLAAC addresses to be added. 755 * 756 * If this function is not called, the default filter used by SLAAC module will be NULL (filtering is disabled). 757 * 758 * @param[in] aInstance A pointer to an OpenThread instance. 759 * @param[in] aFilter A pointer to SLAAC prefix filter handler, or NULL to disable filtering. 760 * 761 */ 762 void otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter); 763 764 /** 765 * This function pointer is called with results of `otIp6RegisterMulticastListeners`. 766 * 767 * @param[in] aContext A pointer to the user context. 768 * @param[in] aError OT_ERROR_NONE when successfully sent MLR.req and received MLR.rsp, 769 * OT_ERROR_RESPONSE_TIMEOUT when failed to receive MLR.rsp, 770 * OT_ERROR_PARSE when failed to parse MLR.rsp. 771 * @param[in] aMlrStatus The Multicast Listener Registration status when @p aError is OT_ERROR_NONE. 772 * @param[in] aFailedAddresses A pointer to the failed IPv6 addresses when @p aError is OT_ERROR_NONE. 773 * @param[in] aFailedAddressNum The number of failed IPv6 addresses when @p aError is OT_ERROR_NONE. 774 * 775 * @sa otIp6RegisterMulticastListeners 776 * 777 */ 778 typedef void (*otIp6RegisterMulticastListenersCallback)(void * aContext, 779 otError aError, 780 uint8_t aMlrStatus, 781 const otIp6Address *aFailedAddresses, 782 uint8_t aFailedAddressNum); 783 784 #define OT_IP6_MAX_MLR_ADDRESSES 15 ///< Max number of IPv6 addresses supported by Multicast Listener Registration. 785 786 /** 787 * This function registers Multicast Listeners to Primary Backbone Router. 788 * 789 * Note: only available when both `OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE` and 790 * `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` are enabled) 791 * 792 * @param[in] aInstance A pointer to an OpenThread instance. 793 * @param[in] aAddresses A Multicast Address Array to register. 794 * @param[in] aAddressNum The number of Multicast Address to register (0 if @p aAddresses is NULL). 795 * @param[in] aTimeout A pointer to the timeout value (in seconds) to be included in MLR.req. A timeout value of 0 796 * removes the corresponding Multicast Listener. If NULL, MLR.req would have no Timeout Tlv by 797 * default. 798 * @param[in] aCallback A pointer to the callback function. 799 * @param[in] aContext A pointer to the user context. 800 * 801 * @retval OT_ERROR_NONE Successfully sent MLR.req. The @p aCallback will be called iff this method 802 * returns OT_ERROR_NONE. 803 * @retval OT_ERROR_BUSY If a previous registration was ongoing. 804 * @retval OT_ERROR_INVALID_ARGS If one or more arguments are invalid. 805 * @retval OT_ERROR_INVALID_STATE If the device was not in a valid state to send MLR.req (e.g. Commissioner not 806 * started, Primary Backbone Router not found). 807 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 808 * 809 * @sa otIp6RegisterMulticastListenersCallback 810 * 811 */ 812 otError otIp6RegisterMulticastListeners(otInstance * aInstance, 813 const otIp6Address * aAddresses, 814 uint8_t aAddressNum, 815 const uint32_t * aTimeout, 816 otIp6RegisterMulticastListenersCallback aCallback, 817 void * aContext); 818 819 /** 820 * This function sets the Mesh Local IID (for test purpose). 821 * 822 * Only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 823 * 824 * @param[in] aInstance A pointer to an OpenThread instance. 825 * @param[in] aIid A pointer to the Mesh Local IID to set. 826 * 827 * @retval OT_ERROR_NONE Successfully set the Mesh Local IID. 828 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 829 * 830 */ 831 otError otIp6SetMeshLocalIid(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 832 833 /** 834 * This function converts a given IP protocol number to a human-readable string. 835 * 836 * @param[in] aIpProto An IP protocol number (`OT_IP6_PROTO_*` enumeration). 837 * 838 * @returns A string representing @p aIpProto. 839 * 840 */ 841 const char *otIp6ProtoToString(uint8_t aIpProto); 842 843 /** 844 * @} 845 * 846 */ 847 848 #ifdef __cplusplus 849 } // extern "C" 850 #endif 851 852 #endif // OPENTHREAD_IP6_H_ 853