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