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