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