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 * Brings the IPv6 interface up or down. 261 * 262 * Call this to enable or 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 * 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 * Adds 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 * Removes 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 * Gets 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 * Subscribes 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 * Unsubscribes 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 * Gets 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 * Checks 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 * Enables or disables 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 @p aString and updated @p aAddress. 614 * @retval OT_ERROR_PARSE Failed to parse @p aString as an IPv6 address. 615 * 616 */ 617 otError otIp6AddressFromString(const char *aString, otIp6Address *aAddress); 618 619 /** 620 * This function converts a human-readable IPv6 prefix string into a binary representation. 621 * 622 * The @p aString parameter should be a string in the format "<address>/<plen>", where `<address>` is an IPv6 623 * address and `<plen>` is a prefix length. 624 * 625 * @param[in] aString A pointer to a NULL-terminated string. 626 * @param[out] aPrefix A pointer to an IPv6 prefix. 627 * 628 * @retval OT_ERROR_NONE Successfully parsed the string as an IPv6 prefix and updated @p aPrefix. 629 * @retval OT_ERROR_PARSE Failed to parse @p aString as an IPv6 prefix. 630 * 631 */ 632 otError otIp6PrefixFromString(const char *aString, otIp6Prefix *aPrefix); 633 634 #define OT_IP6_ADDRESS_STRING_SIZE 40 ///< Recommended size for string representation of an IPv6 address. 635 636 /** 637 * This function converts a given IPv6 address to a human-readable string. 638 * 639 * The IPv6 address string is formatted as 16 hex values separated by ':' (i.e., "%x:%x:%x:...:%x"). 640 * 641 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 642 * but the outputted string is always null-terminated. 643 * 644 * @param[in] aAddress A pointer to an IPv6 address (MUST NOT be NULL). 645 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 646 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_ADDRESS_STRING_SIZE`. 647 * 648 */ 649 void otIp6AddressToString(const otIp6Address *aAddress, char *aBuffer, uint16_t aSize); 650 651 #define OT_IP6_SOCK_ADDR_STRING_SIZE 48 ///< Recommended size for string representation of an IPv6 socket address. 652 653 /** 654 * This function converts a given IPv6 socket address to a human-readable string. 655 * 656 * The IPv6 socket address string is formatted as [`address`]:`port` where `address` is shown 657 * as 16 hex values separated by `:` and `port` is the port number in decimal format, 658 * for example "[%x:%x:...:%x]:%u". 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] aSockAddr A pointer to an IPv6 socket address (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_SOCK_ADDR_STRING_SIZE`. 666 * 667 */ 668 void otIp6SockAddrToString(const otSockAddr *aSockAddr, char *aBuffer, uint16_t aSize); 669 670 #define OT_IP6_PREFIX_STRING_SIZE 45 ///< Recommended size for string representation of an IPv6 prefix. 671 672 /** 673 * This function converts a given IPv6 prefix to a human-readable string. 674 * 675 * The IPv6 address string is formatted as "%x:%x:%x:...[::]/plen". 676 * 677 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated 678 * but the outputted string is always null-terminated. 679 * 680 * @param[in] aPrefix A pointer to an IPv6 prefix (MUST NOT be NULL). 681 * @param[out] aBuffer A pointer to a char array to output the string (MUST NOT be NULL). 682 * @param[in] aSize The size of @p aBuffer (in bytes). Recommended to use `OT_IP6_PREFIX_STRING_SIZE`. 683 * 684 */ 685 void otIp6PrefixToString(const otIp6Prefix *aPrefix, char *aBuffer, uint16_t aSize); 686 687 /** 688 * This function returns the prefix match length (bits) for two IPv6 addresses. 689 * 690 * @param[in] aFirst A pointer to the first IPv6 address. 691 * @param[in] aSecond A pointer to the second IPv6 address. 692 * 693 * @returns The prefix match length in bits. 694 * 695 */ 696 uint8_t otIp6PrefixMatch(const otIp6Address *aFirst, const otIp6Address *aSecond); 697 698 /** 699 * This method gets a prefix with @p aLength from @p aAddress. 700 * 701 * @param[in] aAddress A pointer to an IPv6 address. 702 * @param[in] aLength The length of prefix in bits. 703 * @param[out] aPrefix A pointer to output the IPv6 prefix. 704 * 705 */ 706 void otIp6GetPrefix(const otIp6Address *aAddress, uint8_t aLength, otIp6Prefix *aPrefix); 707 708 /** 709 * This function indicates whether or not a given IPv6 address is the Unspecified Address. 710 * 711 * @param[in] aAddress A pointer to an IPv6 address. 712 * 713 * @retval TRUE If the IPv6 address is the Unspecified Address. 714 * @retval FALSE If the IPv6 address is not the Unspecified Address. 715 * 716 */ 717 bool otIp6IsAddressUnspecified(const otIp6Address *aAddress); 718 719 /** 720 * This function perform OpenThread source address selection. 721 * 722 * @param[in] aInstance A pointer to an OpenThread instance. 723 * @param[in,out] aMessageInfo A pointer to the message information. 724 * 725 * @retval OT_ERROR_NONE Found a source address and is filled into mSockAddr of @p aMessageInfo. 726 * @retval OT_ERROR_NOT_FOUND No source address was found and @p aMessageInfo is unchanged. 727 * 728 */ 729 otError otIp6SelectSourceAddress(otInstance *aInstance, otMessageInfo *aMessageInfo); 730 731 /** 732 * This function indicates whether the SLAAC module is enabled or not. 733 * 734 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 735 * 736 * @retval TRUE SLAAC module is enabled. 737 * @retval FALSE SLAAC module is disabled. 738 * 739 */ 740 bool otIp6IsSlaacEnabled(otInstance *aInstance); 741 742 /** 743 * This function enables/disables the SLAAC module. 744 * 745 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 746 * 747 * When SLAAC module is enabled, SLAAC addresses (based on on-mesh prefixes in Network Data) are added to the interface. 748 * When SLAAC module is disabled any previously added SLAAC address is removed. 749 * 750 * @param[in] aInstance A pointer to an OpenThread instance. 751 * @param[in] aEnabled TRUE to enable, FALSE to disable. 752 * 753 */ 754 void otIp6SetSlaacEnabled(otInstance *aInstance, bool aEnabled); 755 756 /** 757 * This function pointer allows user to filter prefixes and not allow an SLAAC address based on a prefix to be added. 758 * 759 * `otIp6SetSlaacPrefixFilter()` can be used to set the filter handler. The filter handler is invoked by SLAAC module 760 * when it is about to add a SLAAC address based on a prefix. Its boolean return value determines whether the address 761 * is filtered (not added) or not. 762 * 763 * @param[in] aInstance A pointer to an OpenThread instance. 764 * @param[in] aPrefix A pointer to prefix for which SLAAC address is about to be added. 765 * 766 * @retval TRUE Indicates that the SLAAC address based on the prefix should be filtered and NOT added. 767 * @retval FALSE Indicates that the SLAAC address based on the prefix should be added. 768 * 769 */ 770 typedef bool (*otIp6SlaacPrefixFilter)(otInstance *aInstance, const otIp6Prefix *aPrefix); 771 772 /** 773 * This function sets the SLAAC module filter handler. 774 * 775 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_SLAAC_ENABLE` to be enabled. 776 * 777 * The filter handler is called by SLAAC module when it is about to add a SLAAC address based on a prefix to decide 778 * whether the address should be added or not. 779 * 780 * A NULL filter handler disables filtering and allows all SLAAC addresses to be added. 781 * 782 * If this function is not called, the default filter used by SLAAC module will be NULL (filtering is disabled). 783 * 784 * @param[in] aInstance A pointer to an OpenThread instance. 785 * @param[in] aFilter A pointer to SLAAC prefix filter handler, or NULL to disable filtering. 786 * 787 */ 788 void otIp6SetSlaacPrefixFilter(otInstance *aInstance, otIp6SlaacPrefixFilter aFilter); 789 790 /** 791 * This function pointer is called with results of `otIp6RegisterMulticastListeners`. 792 * 793 * @param[in] aContext A pointer to the user context. 794 * @param[in] aError OT_ERROR_NONE when successfully sent MLR.req and received MLR.rsp, 795 * OT_ERROR_RESPONSE_TIMEOUT when failed to receive MLR.rsp, 796 * OT_ERROR_PARSE when failed to parse MLR.rsp. 797 * @param[in] aMlrStatus The Multicast Listener Registration status when @p aError is OT_ERROR_NONE. 798 * @param[in] aFailedAddresses A pointer to the failed IPv6 addresses when @p aError is OT_ERROR_NONE. 799 * @param[in] aFailedAddressNum The number of failed IPv6 addresses when @p aError is OT_ERROR_NONE. 800 * 801 * @sa otIp6RegisterMulticastListeners 802 * 803 */ 804 typedef void (*otIp6RegisterMulticastListenersCallback)(void *aContext, 805 otError aError, 806 uint8_t aMlrStatus, 807 const otIp6Address *aFailedAddresses, 808 uint8_t aFailedAddressNum); 809 810 #define OT_IP6_MAX_MLR_ADDRESSES 15 ///< Max number of IPv6 addresses supported by Multicast Listener Registration. 811 812 /** 813 * This function registers Multicast Listeners to Primary Backbone Router. 814 * 815 * Note: only available when both `OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE` and 816 * `OPENTHREAD_CONFIG_COMMISSIONER_ENABLE` are enabled) 817 * 818 * @param[in] aInstance A pointer to an OpenThread instance. 819 * @param[in] aAddresses A Multicast Address Array to register. 820 * @param[in] aAddressNum The number of Multicast Address to register (0 if @p aAddresses is NULL). 821 * @param[in] aTimeout A pointer to the timeout value (in seconds) to be included in MLR.req. A timeout value of 0 822 * removes the corresponding Multicast Listener. If NULL, MLR.req would have no Timeout Tlv by 823 * default. 824 * @param[in] aCallback A pointer to the callback function. 825 * @param[in] aContext A pointer to the user context. 826 * 827 * @retval OT_ERROR_NONE Successfully sent MLR.req. The @p aCallback will be called iff this method 828 * returns OT_ERROR_NONE. 829 * @retval OT_ERROR_BUSY If a previous registration was ongoing. 830 * @retval OT_ERROR_INVALID_ARGS If one or more arguments are invalid. 831 * @retval OT_ERROR_INVALID_STATE If the device was not in a valid state to send MLR.req (e.g. Commissioner not 832 * started, Primary Backbone Router not found). 833 * @retval OT_ERROR_NO_BUFS If insufficient message buffers available. 834 * 835 * @sa otIp6RegisterMulticastListenersCallback 836 * 837 */ 838 otError otIp6RegisterMulticastListeners(otInstance *aInstance, 839 const otIp6Address *aAddresses, 840 uint8_t aAddressNum, 841 const uint32_t *aTimeout, 842 otIp6RegisterMulticastListenersCallback aCallback, 843 void *aContext); 844 845 /** 846 * This function sets the Mesh Local IID (for test purpose). 847 * 848 * Only available when `OPENTHREAD_CONFIG_REFERENCE_DEVICE_ENABLE` is enabled. 849 * 850 * @param[in] aInstance A pointer to an OpenThread instance. 851 * @param[in] aIid A pointer to the Mesh Local IID to set. 852 * 853 * @retval OT_ERROR_NONE Successfully set the Mesh Local IID. 854 * @retval OT_ERROR_INVALID_STATE Thread protocols are enabled. 855 * 856 */ 857 otError otIp6SetMeshLocalIid(otInstance *aInstance, const otIp6InterfaceIdentifier *aIid); 858 859 /** 860 * This function converts a given IP protocol number to a human-readable string. 861 * 862 * @param[in] aIpProto An IP protocol number (`OT_IP6_PROTO_*` enumeration). 863 * 864 * @returns A string representing @p aIpProto. 865 * 866 */ 867 const char *otIp6ProtoToString(uint8_t aIpProto); 868 869 /** 870 * This structure represents the counters for packets and bytes. 871 * 872 */ 873 typedef struct otPacketsAndBytes 874 { 875 uint64_t mPackets; ///< The number of packets. 876 uint64_t mBytes; ///< The number of bytes. 877 } otPacketsAndBytes; 878 879 /** 880 * This structure represents the counters of packets forwarded via Border Routing. 881 * 882 */ 883 typedef struct otBorderRoutingCounters 884 { 885 otPacketsAndBytes mInboundUnicast; ///< The counters for inbound unicast. 886 otPacketsAndBytes mInboundMulticast; ///< The counters for inbound multicast. 887 otPacketsAndBytes mOutboundUnicast; ///< The counters for outbound unicast. 888 otPacketsAndBytes mOutboundMulticast; ///< The counters for outbound multicast. 889 uint32_t mRaRx; ///< The number of received RA packets. 890 uint32_t mRaTxSuccess; ///< The number of RA packets successfully transmitted. 891 uint32_t mRaTxFailure; ///< The number of RA packets failed to transmit. 892 uint32_t mRsRx; ///< The number of received RS packets. 893 uint32_t mRsTxSuccess; ///< The number of RS packets successfully transmitted. 894 uint32_t mRsTxFailure; ///< The number of RS packets failed to transmit. 895 } otBorderRoutingCounters; 896 897 /** 898 * Gets the Border Routing counters. 899 * 900 * This function requires the build-time feature `OPENTHREAD_CONFIG_IP6_BR_COUNTERS_ENABLE` to be enabled. 901 * 902 * @param[in] aInstance A pointer to an OpenThread instance. 903 * 904 * @returns A pointer to the Border Routing counters. 905 * 906 */ 907 const otBorderRoutingCounters *otIp6GetBorderRoutingCounters(otInstance *aInstance); 908 909 /** 910 * Resets the Border Routing counters. 911 * 912 * @param[in] aInstance A pointer to an OpenThread instance. 913 * 914 */ 915 void otIp6ResetBorderRoutingCounters(otInstance *aInstance); 916 917 /** 918 * @} 919 * 920 */ 921 922 #ifdef __cplusplus 923 } // extern "C" 924 #endif 925 926 #endif // OPENTHREAD_IP6_H_ 927
