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